> ## Documentation Index > Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create program member > Enrolls a customer as a member of the loyalty program. The program must be in `ACTIVE` status (returns a `423` error otherwise) and the customer must exist in Voucherify. A customer can be a member of a given program only once - creating a second member for the same customer ID returns `409` error (`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. ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members openapi: 3.1.0 info: title: Voucherify Loyalty v2 API version: 2.0.0 description: >- Complete OpenAPI specification for the Voucherify Loyalty v2 API. All endpoints require the LOYALTY_V2 feature flag. Combined from per-domain specs: programs.yaml, members.yaml, program-operations.yaml, card-definitions.yaml, earning-rules.yaml, tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml servers: - url: '{protocol}://{host}' variables: protocol: default: https enum: - https - http host: default: api.voucherify.io security: - X-App-Id: [] X-App-Token: [] - bearerAuth: [] tags: - name: Programs description: >- Loyalty program CRUD, lifecycle management, program-scoped resource assignments (card definitions, earning rules, rewards, tier structures), member management (create, list, get, activate, deactivate, delete), membership retrieval (member + program + cards with tier progress, by customer ID, customer source ID, or member ID), card operations (points adjustment, pending points, expiring points, transactions), reward purchases, and activity history. - name: Card Definitions description: >- CRUD operations, lifecycle management, and activity history for card definitions. Card definitions describe the configuration for loyalty cards, including code generation, points expiration, earning/spending limits, pending points, refunds, and balance settings. - name: Earning Rules description: >- Manage earning rules that define how customers earn points or receive incentives based on triggers (events, segments, custom events). Includes CRUD, lifecycle, and activity history. - name: Tier Structures description: >- CRUD operations, lifecycle management, and activity history for tier structures. Includes nested tier definitions (create, list, update, delete) within tier structures. Tier structures define the tiering model for loyalty programs — how members qualify for and move between tiers. - name: Benefits description: >- Manage benefit definitions (fixed points, proportional points, material, digital). Includes CRUD, lifecycle transitions, and activity history. - name: Rewards description: >- CRUD, lifecycle operations, and activity history for reward definitions. Rewards can be material (product/SKU) or digital (discount coupons, gift vouchers). - name: Examine description: >- Evaluation endpoints that estimate earning opportunities and reward availability for a customer across their loyalty program memberships, without side effects. paths: /v2/loyalties/programs/{programId}/members: post: tags: - Programs summary: Create program member description: >- Enrolls a customer as a member of the loyalty program. The program must be in `ACTIVE` status (returns a `423` error otherwise) and the customer must exist in Voucherify. A customer can be a member of a given program only once - creating a second member for the same customer ID returns `409` error (`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. operationId: createProgramMember parameters: - name: programId in: path required: true description: Unique loyalty program ID (format `lprg_[a-f0-9]+`). schema: type: string pattern: ^lprg_[a-f0-9]+$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MemberCreateRequest' responses: '200': description: The created member with its automatically created cards. content: application/json: schema: $ref: '#/components/schemas/MemberCreateResponse' examples: Member added to the program: value: id: lmbr_12ba1c1a8456b6db8c customer_id: cust_X07elh40iNWLujRmDNmBufxd program_id: lprg_128f58429f4c4bf7b2 status: ACTIVE metadata: {} created_at: '2026-07-14T16:41:01.201Z' updated_at: null object: member cards: - member_role: OWNER created_at: '2026-07-14T16:41:01.214Z' card: id: lcrd_12ba1c1a86d6b6db8f card_definition_id: lcdef_128f495f720c4bec8c card_type: INDIVIDUAL code: null 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: null next_activation: null object: card object: member_card - member_role: OWNER created_at: '2026-07-14T16:41:01.214Z' card: id: lcrd_12ba1c1a86d6b6db90 card_definition_id: lcdef_128f49963c0c4becb7 card_type: INDIVIDUAL code: null 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: null next_activation: null object: card object: member_card - member_role: OWNER created_at: '2026-07-14T16:41:01.214Z' card: id: lcrd_12ba1c1a86d6b6db91 card_definition_id: lcdef_128f4a88414c4bed69 card_type: INDIVIDUAL code: null 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: null next_activation: null object: card object: member_card '400': description: >- Validation error - request body or path parameters failed validation, or the operation is not allowed in the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Member not found: value: code: 404 key: not_found message: Resource not found details: Cannot find customer with id cust_X07elh40iNWLujRmDNmBufd request_id: v-12c30587d84f93b9af resource_id: cust_X07elh40iNWLujRmDNmBufd resource_type: customer '409': description: >- Conflict - the customer with a given ID has already been added to the loyalty program. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Member already exists: value: code: 409 key: member_already_exists message: Member already exists details: >- Customer 'cust_X07elh40iNWLujRmDNmBufxd' already is a member of program 'lprg_128f58429f4c4bf7b2' request_id: v-12c3021e930a67865c '423': description: Program is not in ACTIVE status. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Non-active program: value: code: 423 key: non_active_program message: Invalid program status details: Cannot create member when program status is not ACTIVE request_id: v-... '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: MemberCreateRequest: type: object title: Create program member request description: >- Request body for creating a program member. No additional properties are allowed. allOf: - $ref: '#/components/schemas/MemberCreate' MemberCreateResponse: $ref: '#/components/schemas/MemberWithCards' ErrorResponse: type: object description: Standard error response returned by all Loyalty v2 endpoints. properties: code: type: integer description: HTTP status code of the error. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional details about the error. request_id: type: string description: Unique identifier of the request that produced the error. resource_id: type: string description: Unique identifier of the resource that produced the error. resource_type: type: string description: Type of the resource that produced the error. MemberCreate: type: object properties: customer_id: type: string pattern: ^cust_[a-zA-Z0-9]+ description: >- Unique Voucherify customer ID of an existing customer to enroll as a member. Required. status: description: Initial member status. Defaults to `ACTIVE` when omitted or `null`. oneOf: - type: string enum: - ACTIVE - INACTIVE - type: 'null' default: ACTIVE metadata: description: >- 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. oneOf: - type: object - type: 'null' default: {} required: - customer_id MemberWithCards: description: >- A loyalty program member together with its loyalty cards. Returned by member create and get endpoints. allOf: - $ref: '#/components/schemas/Member' - type: object properties: cards: description: >- 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. type: array items: $ref: '#/components/schemas/MemberCard' required: - cards Member: type: object description: A loyalty program member. properties: id: type: string pattern: ^lmbr_[a-f0-9]+$ description: Unique member ID. customer_id: type: string pattern: ^cust_[a-zA-Z0-9]+ description: Unique Voucherify ID of the customer enrolled as this member. program_id: type: string pattern: ^lprg_[a-f0-9]+$ description: Unique Voucherify ID of the loyalty program the member belongs to. status: type: string enum: - ACTIVE - INACTIVE - DELETED description: >- Current member status. `INACTIVE` member can't earn points or redeem rewards. metadata: type: object description: Free-form metadata attached to the member (empty object when none). created_at: type: string format: date-time description: Timestamp when the member was created (ISO 8601). updated_at: type: - string - 'null' format: date-time description: >- Timestamp when the member was last updated (ISO 8601), or `null` if never updated. object: type: string const: member description: Object type marker, always `member`. required: - id - customer_id - program_id - status - metadata - created_at - updated_at - object MemberCard: type: object description: >- A member's loyalty card - the member's assignment to the card (`member_role`, `created_at`) combined with the card details in the `card` object. properties: member_role: type: string enum: - OWNER - MEMBER description: >- Role of the member on this card. Currently, loyalty program members can have only the `OWNER` role. created_at: type: string format: date-time description: Timestamp when the card was assigned to the member (ISO 8601). card: description: The loyalty card details, or `null` when the card is not available. oneOf: - $ref: '#/components/schemas/CardSimple' - type: 'null' object: type: string const: member_card description: Object type marker, always `member_card`. required: - member_role - created_at - card - object CardSimple: type: object description: >- A loyalty card in its simple representation, as embedded in member responses. properties: id: type: string pattern: ^lcrd_[a-f0-9]+$ description: Unique Voucherify ID of the card. card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: >- Unique Voucherify ID of the card definition the card was created from. card_type: type: string enum: - INDIVIDUAL description: Card type. Currently only `INDIVIDUAL` is supported. code: type: - string - 'null' description: >- Human-readable card code. Card code generation is asynchronous - this field is `null` right after member creation and is populated shortly after, once the background code generation completes. lifetime_bucket: $ref: '#/components/schemas/CardLifetimeBucket' description: Lifetime point counters of the card. balance: $ref: '#/components/schemas/CardBalance' description: Current available balance calculated from the lifetime bucket. next_expiration: description: >- The nearest upcoming point expiration, or `null` when none is scheduled. oneOf: - $ref: '#/components/schemas/CardNextExpiration' - type: 'null' next_activation: description: >- The nearest upcoming pending point activation, or `null` when none is scheduled. oneOf: - $ref: '#/components/schemas/CardNextActivation' - type: 'null' object: type: string const: card description: Object type marker, always `card`. required: - id - card_definition_id - card_type - code - lifetime_bucket - balance - next_expiration - next_activation - object CardLifetimeBucket: type: object description: Lifetime points counters of a card. properties: points: $ref: '#/components/schemas/CardLifetimeBucketPoints' description: Lifetime counters of regular (active) points. pending_points: $ref: '#/components/schemas/CardLifetimeBucketPendingPoints' description: Lifetime counters of pending points. required: - points - pending_points CardBalance: type: object description: Current available balance of a card. properties: points: type: number description: Currently available regular points. default: 0 pending_points: type: number description: Currently pending (not yet activated) points. default: 0 required: - points - pending_points CardNextExpiration: type: object description: The nearest upcoming points expiration on a card. properties: points: type: number description: Number of points that will expire. default: 0 date: type: string format: date description: Date when the points expire (`YYYY-MM-DD`). required: - points - date CardNextActivation: type: object description: >- The nearest upcoming pending points activation on a card. For the `EVENT_BASED` type, `date` is omitted and `cancel_date` is returned instead; for other types `date` is returned and `cancel_date` is omitted. properties: points: type: number description: Number of pending points to be activated. default: 0 type: type: string enum: - IMMEDIATE - PERIOD_BASED - FIXED_DATES - EVENT_BASED description: Pending points activation type from the card definition. date: type: string format: date description: >- Activation date (`YYYY-MM-DD`). Present for all types except `EVENT_BASED`. cancel_date: type: string format: date description: >- Date when the pending points are canceled if the activating event does not occur (`YYYY-MM-DD`). Present only for the `EVENT_BASED` type. required: - points - type CardLifetimeBucketPoints: type: object description: >- Lifetime counters of regular points. All counters default to 0. The available balance is calculated as: `total` - `subtracted` - `expired` - `spent` - `refunded` + `returned` - `locked` + `unlocked` - `purchased_reversed`. properties: total: type: number description: >- Total accumulated points, including points added manually, earned by fulfilling earning rules and activated from pending points (excluding returned points). default: 0 earned: type: number description: >- Total points earned by fulfilling earning rules (does not include activated pending points or points added manually). default: 0 added: type: number description: Total manually added points. default: 0 purchased: type: number description: >- Total points purchased via a `LOYALTY_CARD_POINTS` reward (credited to the target card). default: 0 purchased_reversed: type: number description: Total purchased points reversed via reward refund. default: 0 subtracted: type: number description: Total manually subtracted points. default: 0 expired: type: number description: Total expired points. default: 0 spent: type: number description: Total points spent on rewards. default: 0 refunded: type: number description: >- Total refunded points (points that were earned by products which were later returned). default: 0 returned: type: number description: Total returned points (by returning a purchased reward). default: 0 locked: type: number description: Total locked points (by locking a purchased reward). default: 0 unlocked: type: number description: Total unlocked points (by unlocking a purchased reward). default: 0 required: - total - earned - added - purchased - purchased_reversed - subtracted - expired - spent - refunded - returned - locked - unlocked CardLifetimeBucketPendingPoints: type: object description: >- Lifetime counters of pending points. The available pending balance is max(`total` - `activated` - `canceled`, 0). properties: total: type: number description: Total pending points ever added. default: 0 activated: type: number description: Total pending points activated into regular points. default: 0 canceled: type: number description: Total pending points canceled. default: 0 required: - total - activated - canceled securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header bearerAuth: type: http scheme: bearer bearerFormat: JWT ````