Create a program member

curl --request POST \
  --url {protocol}://{host}/v2/loyalties/programs/{programId}/members \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer_id": "<string>",
  "status": "ACTIVE",
  "metadata": {}
}
'

{
  "id": "<string>",
  "customer_id": "<string>",
  "program_id": "<string>",
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "cards": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "tier_progress": {
        "current": {
          "id": "<string>",
          "name": "<string>",
          "activated_at": "2023-11-07T05:31:56Z",
          "expires_at": "2023-11-07T05:31:56Z",
          "points": {
            "current": 123,
            "min": 123,
            "max": 123
          }
        },
        "tier_structure": {
          "id": "<string>",
          "object": "<string>"
        },
        "risks": [
          {
            "date": "2023-11-07T05:31:56Z",
            "tier_id": "<string>"
          }
        ],
        "opportunities": [
          {
            "valid_until": "2023-11-07T05:31:56Z",
            "tier_id": "<string>",
            "points": 123
          }
        ],
        "object": "<string>"
      },
      "card": {
        "id": "<string>",
        "card_definition_id": "<string>",
        "card_type": "INDIVIDUAL",
        "code": "<string>",
        "lifetime_bucket": {
          "points": {
            "total": 0,
            "earned": 0,
            "added": 0,
            "purchased": 0,
            "purchased_reversed": 0,
            "subtracted": 0,
            "expired": 0,
            "spent": 0,
            "refunded": 0,
            "returned": 0,
            "locked": 0,
            "unlocked": 0
          },
          "pending_points": {
            "total": 0,
            "activated": 0,
            "canceled": 0
          }
        },
        "balance": {
          "points": 0,
          "pending_points": 0
        },
        "next_expiration": {
          "points": 0,
          "date": "2023-12-25"
        },
        "next_activation": {
          "points": 0,
          "date": "2023-12-25",
          "cancel_date": "2023-12-25"
        },
        "object": "<string>"
      },
      "object": "<string>"
    }
  ]
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

Create a program member

⚠️ BETA endpoint

This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager.

Enrolls a customer as a member of the loyalty program. The program must be in ACTIVE status (423 otherwise) and the customer must exist. A customer can be a member of a given program only once - creating a second member for the same customer returns 409 (member_already_exists).

Loyalty cards are created automatically for all card definitions assigned to the program and returned in the cards array. Card code generation is asynchronous - code may be null immediately after creation.

POST

loyalties

programs

{programId}

members

Create a program member

curl --request POST \
  --url {protocol}://{host}/v2/loyalties/programs/{programId}/members \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer_id": "<string>",
  "status": "ACTIVE",
  "metadata": {}
}
'

{
  "id": "<string>",
  "customer_id": "<string>",
  "program_id": "<string>",
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "cards": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "tier_progress": {
        "current": {
          "id": "<string>",
          "name": "<string>",
          "activated_at": "2023-11-07T05:31:56Z",
          "expires_at": "2023-11-07T05:31:56Z",
          "points": {
            "current": 123,
            "min": 123,
            "max": 123
          }
        },
        "tier_structure": {
          "id": "<string>",
          "object": "<string>"
        },
        "risks": [
          {
            "date": "2023-11-07T05:31:56Z",
            "tier_id": "<string>"
          }
        ],
        "opportunities": [
          {
            "valid_until": "2023-11-07T05:31:56Z",
            "tier_id": "<string>",
            "points": 123
          }
        ],
        "object": "<string>"
      },
      "card": {
        "id": "<string>",
        "card_definition_id": "<string>",
        "card_type": "INDIVIDUAL",
        "code": "<string>",
        "lifetime_bucket": {
          "points": {
            "total": 0,
            "earned": 0,
            "added": 0,
            "purchased": 0,
            "purchased_reversed": 0,
            "subtracted": 0,
            "expired": 0,
            "spent": 0,
            "refunded": 0,
            "returned": 0,
            "locked": 0,
            "unlocked": 0
          },
          "pending_points": {
            "total": 0,
            "activated": 0,
            "canceled": 0
          }
        },
        "balance": {
          "points": 0,
          "pending_points": 0
        },
        "next_expiration": {
          "points": 0,
          "date": "2023-12-25"
        },
        "next_activation": {
          "points": 0,
          "date": "2023-12-25",
          "cancel_date": "2023-12-25"
        },
        "object": "<string>"
      },
      "object": "<string>"
    }
  ]
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id

string

header

required

X-App-Token

string

header

required

Path Parameters

programId

string

required

Loyalty program ID (format lprg_[a-f0-9]+).

Pattern: ^lprg_[a-f0-9]+$

Body

application/json

Request body for creating a program member. No additional properties are allowed.

customer_id

string

required

ID of an existing customer to enroll as a member. Required.

Pattern: ^cust_[a-zA-Z0-9]+

status

enum<string> | null

default:ACTIVE

Initial member status. Defaults to ACTIVE when omitted or null.

Available options:

ACTIVE,

INACTIVE

metadata

object | null

Free-form metadata attached to the member. Validated against the metadata schema defined for the vl_member related object (when one is configured). Defaults to an empty object.

Response

The created member with its automatically created cards.

A loyalty program member together with its loyalty cards. Returned by member create and get endpoints.

string

required

Unique member ID.

Pattern: ^lmbr_[a-f0-9]+$

customer_id

string

required

ID of the customer enrolled as this member.

Pattern: ^cust_[a-zA-Z0-9]+

program_id

string

required

ID of the loyalty program the member belongs to.

Pattern: ^lprg_[a-f0-9]+$

status

enum<string>

required

Current member status.

Available options:

ACTIVE,

INACTIVE,

DELETED

metadata

object

required

Free-form metadata attached to the member (empty object when none).

created_at

string<date-time>

required

Timestamp when the member was created (ISO 8601).

updated_at

string<date-time> | null

required

Timestamp when the member was last updated (ISO 8601), or null if never updated.

object

string

required

Object type marker, always member.

Allowed value: "member"

cards

object[] | null

required

Member's loyalty cards - one per card definition assigned to the program. Card codes are generated asynchronously, so card.code may be null right after member creation.

Show child attributes

Last modified on July 13, 2026

List program members Batch create program members

⌘I

Card Definitions

Programs

Members

Examine

Earning Rules

Tier Structures

Benefits

Rewards

Create a program member

Authorizations

Path Parameters

Body

Response