> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## 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: - bearerAuth: [] X-App-Id: [] X-App-Token: [] 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), 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 a program member description: > ⚠️ **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. operationId: createProgramMember parameters: - name: programId in: path required: true description: 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/MemberWithCards' '400': description: >- Validation error - request body or query 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' '409': description: Conflict - e.g. duplicate resource or invalid state transition. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '423': description: >- Resource locked - a related resource is in a state that prevents this operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: MemberCreateRequest: type: object description: > Request body for creating a program member. No additional properties are allowed. properties: customer_id: type: string pattern: ^cust_[a-zA-Z0-9]+ description: 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 additionalProperties: false 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. oneOf: - type: array items: $ref: '#/components/schemas/MemberCard' - type: 'null' required: - cards 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: Identifier of the request that produced the error. 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: ID of the customer enrolled as this member. program_id: type: string pattern: ^lprg_[a-f0-9]+$ description: ID of the loyalty program the member belongs to. status: type: string enum: - ACTIVE - INACTIVE - DELETED description: Current member status. 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. created_at: type: string format: date-time description: Timestamp when the card was assigned to the member (ISO 8601). tier_progress: description: > Member's tier progress on this card. Present only when a tier structure is assigned to the card's card definition and the member has a tier; null otherwise. oneOf: - $ref: '#/components/schemas/MemberTierProgress' - type: 'null' 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 - tier_progress - card - object MemberTierProgress: type: object description: Member's tier progress on a card. properties: current: description: The member's current tier, or null. oneOf: - $ref: '#/components/schemas/MemberTierProgressCurrent' - type: 'null' tier_structure: description: Reference to the tier structure the progress relates to, or null. oneOf: - $ref: '#/components/schemas/MemberTierProgressTierStructure' - type: 'null' risks: type: array description: Upcoming risks of losing or downgrading the current tier. items: $ref: '#/components/schemas/MemberTierProgressRisk' opportunities: type: array description: Opportunities to reach higher tiers. items: $ref: '#/components/schemas/MemberTierProgressOpportunity' object: type: string const: member_tier_progress description: Object type marker, always `member_tier_progress`. required: - current - tier_structure - risks - opportunities - 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 card ID. card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: 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 points counters of the card. balance: $ref: '#/components/schemas/CardBalance' description: Current available balance calculated from the lifetime bucket. next_expiration: description: >- The nearest upcoming points expiration, or null when none is scheduled. oneOf: - $ref: '#/components/schemas/CardNextExpiration' - type: 'null' next_activation: description: >- The nearest upcoming pending points 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 MemberTierProgressCurrent: type: object description: The member's current tier. properties: id: type: string pattern: ^lt_[a-f0-9]+$ description: Tier ID. name: type: string description: Tier name. activated_at: type: - string - 'null' format: date-time description: >- Timestamp when the tier was activated for the member (ISO 8601), or null. expires_at: type: - string - 'null' format: date-time description: Timestamp when the member's tier expires (ISO 8601), or null. points: description: Member's points position within the tier's points range, or null. oneOf: - $ref: '#/components/schemas/MemberTierProgressPoints' - type: 'null' required: - id - name - activated_at - expires_at - points MemberTierProgressTierStructure: type: object description: Simple tier structure reference. properties: id: type: string pattern: ^lts_[a-f0-9]+$ description: Tier structure ID. object: type: string const: tier_structure description: Object type marker, always `tier_structure`. required: - id - object MemberTierProgressRisk: type: object description: A risk of losing or downgrading the current tier. properties: type: type: string enum: - TIER_DOWNGRADE - TIER_LEFT description: > Risk type - `TIER_DOWNGRADE` when the member would fall to a lower tier, `TIER_LEFT` when the member would leave the tier structure entirely. date: type: - string - 'null' format: date-time description: Date when the risk materializes (ISO 8601), or null. tier_id: type: - string - 'null' description: >- ID of the tier the member would be downgraded to (`lt_[a-f0-9]+`), or null for `TIER_LEFT`. required: - type - date - tier_id MemberTierProgressOpportunity: type: object description: An opportunity to reach a higher tier. properties: valid_until: type: - string - 'null' format: date-time description: >- Deadline for taking advantage of the opportunity (ISO 8601), or null. tier_id: type: - string - 'null' description: ID of the tier that can be reached (`lt_[a-f0-9]+`), or null. points: type: number description: Points needed to reach the tier. required: - valid_until - tier_id - points 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 MemberTierProgressPoints: type: object description: Points position within a tier. properties: current: type: number description: Member's current points counted towards the tier. min: type: number description: Minimum points of the tier's range. max: type: number description: Maximum points of the tier's range. required: - current - min - max 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: bearerAuth: type: http scheme: bearer bearerFormat: JWT X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header ````