> ## 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 program > ⚠️ **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. Creates a new loyalty program. The program can be created with status `DRAFT` (default) or `ACTIVE`. When created as `ACTIVE`, the program must be connected to at least one active card definition and at least one active earning rule (provided via `card_definitions` and `earning_rules` arrays), otherwise the request is rejected with `423 Locked` (keys `missing_active_card_definition` / `missing_active_earning_rule`). Optionally assigns card definitions, earning rules, rewards and tier structures in the same request. ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/programs 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: post: tags: - Programs summary: Create program 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. Creates a new loyalty program. The program can be created with status `DRAFT` (default) or `ACTIVE`. When created as `ACTIVE`, the program must be connected to at least one active card definition and at least one active earning rule (provided via `card_definitions` and `earning_rules` arrays), otherwise the request is rejected with `423 Locked` (keys `missing_active_card_definition` / `missing_active_earning_rule`). Optionally assigns card definitions, earning rules, rewards and tier structures in the same request. operationId: createProgram requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProgramCreateRequest' responses: '200': description: >- Program created. Response includes the ids of resources assigned during creation. content: application/json: schema: $ref: '#/components/schemas/ProgramCreateResponse' '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: ProgramCreateRequest: type: object description: Payload for creating a loyalty program. properties: name: type: string description: Program name. minLength: 1 maxLength: 200 start_date: type: - string - 'null' format: date-time description: Program validity start date, in ISO 8601 date-time format. end_date: type: - string - 'null' format: date-time description: Program validity end date, in ISO 8601 date-time format. validity_hours: description: Validity hours configuration. Defaults to `ANY_TIME` when omitted. oneOf: - $ref: '#/components/schemas/ProgramValidityHoursUpsert' - type: 'null' status: description: >- Initial program status. Only `ACTIVE` and `DRAFT` are allowed at creation. Defaults to `DRAFT`. oneOf: - type: string enum: - ACTIVE - DRAFT - type: 'null' metadata: description: >- Arbitrary key-value metadata. Validated against the `vl_program` metadata schema definition of the project. Defaults to `{}`. oneOf: - type: object - type: 'null' card_definitions: description: >- Card definitions to assign at creation. Required (with active card definitions) when creating the program with status `ACTIVE`. oneOf: - type: array items: $ref: '#/components/schemas/ProgramCardDefinitionAssignItem' minItems: 1 maxItems: 10 - type: 'null' earning_rules: description: >- Earning rules to assign at creation. Required (with active earning rules) when creating the program with status `ACTIVE`. oneOf: - type: array items: $ref: '#/components/schemas/ProgramEarningRuleAssignItem' minItems: 1 maxItems: 10 - type: 'null' rewards: description: Rewards to assign at creation, each with its stock configuration. oneOf: - type: array items: $ref: '#/components/schemas/ProgramRewardAssignItem' minItems: 1 maxItems: 10 - type: 'null' tier_structures: description: >- Tier structures to assign at creation. A program can have at most one tier structure. oneOf: - type: array items: $ref: '#/components/schemas/ProgramTierStructureAssignItem' minItems: 1 maxItems: 10 - type: 'null' required: - name additionalProperties: false ProgramCreateResponse: description: >- Program create response - the program extended with the ids of resources assigned at creation. allOf: - $ref: '#/components/schemas/Program' - type: object properties: card_definitions: description: >- Card definitions assigned at creation, or null when none were provided. oneOf: - type: array items: $ref: '#/components/schemas/ProgramCreateAssignedCardDefinition' - type: 'null' earning_rules: description: >- Earning rules assigned at creation, or null when none were provided. oneOf: - type: array items: $ref: '#/components/schemas/ProgramCreateAssignedEarningRule' - type: 'null' rewards: description: Rewards assigned at creation, or null when none were provided. oneOf: - type: array items: $ref: '#/components/schemas/ProgramCreateAssignedReward' - type: 'null' tier_structures: description: >- Tier structures assigned at creation, or null when none were provided. oneOf: - type: array items: $ref: '#/components/schemas/ProgramCreateAssignedTierStructure' - type: 'null' 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. ProgramValidityHoursUpsert: type: object description: > Validity hours configuration. When `type` is `ANY_TIME`, `daily` must be omitted or null. When `type` is `DAILY`, `daily` is required and must contain at least one window. properties: type: type: string description: >- Validity hours mode. `ANY_TIME` means the program is always valid; `DAILY` restricts validity to configured daily windows. enum: - DAILY - ANY_TIME daily: description: >- Daily validity windows. Required when `type` is `DAILY`; must be null/omitted when `type` is `ANY_TIME`. oneOf: - type: array minItems: 1 items: $ref: '#/components/schemas/ProgramValidityDailyHoursUpsert' - type: 'null' required: - type additionalProperties: false allOf: - if: properties: type: const: ANY_TIME then: properties: daily: type: 'null' - if: properties: type: const: DAILY then: required: - daily properties: daily: type: array minItems: 1 items: $ref: '#/components/schemas/ProgramValidityDailyHoursUpsert' ProgramCardDefinitionAssignItem: type: object description: Card definition to assign to the program. properties: id: type: string description: Unique card definition identifier. pattern: ^lcdef_[a-f0-9]+$ required: - id additionalProperties: false ProgramEarningRuleAssignItem: type: object description: Earning rule to assign to the program. properties: id: type: string description: Unique earning rule identifier. pattern: ^lern_[a-f0-9]+$ required: - id additionalProperties: false ProgramRewardAssignItem: type: object description: Reward to assign to the program, together with its stock configuration. properties: id: type: string description: Unique reward identifier. pattern: ^lrew_[a-f0-9]+$ stock: $ref: '#/components/schemas/ProgramRewardAssignmentStock' required: - id - stock additionalProperties: false ProgramTierStructureAssignItem: type: object description: Tier structure to assign to the program. properties: id: type: string description: Unique tier structure identifier. pattern: ^lts_[a-f0-9]+$ required: - id additionalProperties: false Program: type: object description: A loyalty program. properties: id: type: string description: Unique program identifier. pattern: ^lprg_[a-f0-9]+$ name: type: string description: Program name. status: type: string description: Program status. enum: - DRAFT - ACTIVE - INACTIVE - DELETED start_date: type: - string - 'null' format: date-time description: Program validity start date (ISO 8601), or null when not set. end_date: type: - string - 'null' format: date-time description: Program validity end date (ISO 8601), or null when not set. validity_hours: $ref: '#/components/schemas/ProgramValidityHours' description: Validity hours configuration. Defaults to type `ANY_TIME`. metadata: type: object description: Arbitrary key-value metadata. Defaults to `{}`. created_at: type: string format: date-time description: Creation timestamp (ISO 8601). updated_at: type: - string - 'null' format: date-time description: Last update timestamp (ISO 8601), or null when never updated. object: type: string description: Object type marker. const: program ProgramCreateAssignedCardDefinition: type: object description: Card definition assigned during program creation. properties: id: type: string description: Unique card definition identifier. pattern: ^lcdef_[a-f0-9]+$ ProgramCreateAssignedEarningRule: type: object description: Earning rule assigned during program creation. properties: id: type: string description: Unique earning rule identifier. pattern: ^lern_[a-f0-9]+$ ProgramCreateAssignedReward: type: object description: Reward assigned during program creation. properties: id: type: string description: Unique reward identifier. pattern: ^lrew_[a-f0-9]+$ stock: $ref: '#/components/schemas/ProgramRewardAssignmentStock' description: >- Stock configuration provided at assignment. Omitted when not provided. ProgramCreateAssignedTierStructure: type: object description: Tier structure assigned during program creation. properties: id: type: string description: Unique tier structure identifier. pattern: ^lts_[a-f0-9]+$ ProgramValidityDailyHoursUpsert: type: object description: A single daily validity-hours window definition. properties: days_of_week: type: array description: >- Days of week the window applies to. 0 = Sunday through 6 = Saturday. Items must be unique. items: type: integer minimum: 0 maximum: 6 minItems: 1 maxItems: 7 uniqueItems: true start_time: type: string description: >- Window start time in `HH:mm` format. If seconds are provided, they are ignored. example: '09:00' end_time: type: string description: >- Window end time in `HH:mm` format. If seconds are provided, they are ignored. example: '17:00' required: - days_of_week - start_time - end_time additionalProperties: false ProgramRewardAssignmentStock: type: object description: > Reward stock configuration. When `type` is `UNLIMITED`, `limited` must not be provided. When `type` is `LIMITED`, `limited` is required. properties: type: type: string description: Stock type. enum: - UNLIMITED - LIMITED limited: description: >- Limited stock details. Required when `type` is `LIMITED`; must not be provided when `type` is `UNLIMITED`. oneOf: - $ref: '#/components/schemas/ProgramRewardAssignmentStockLimited' - type: 'null' required: - type additionalProperties: false allOf: - if: properties: type: const: UNLIMITED then: not: required: - limited - if: properties: type: const: LIMITED then: required: - limited properties: limited: $ref: '#/components/schemas/ProgramRewardAssignmentStockLimited' ProgramValidityHours: type: object description: Validity hours configuration of the program. properties: type: type: string description: Validity hours mode. enum: - DAILY - ANY_TIME daily: type: array description: Daily validity windows. Present only when `type` is `DAILY`. items: $ref: '#/components/schemas/ProgramValidityDailyHours' ProgramRewardAssignmentStockLimited: type: object description: Limited stock configuration. properties: quantity: type: integer description: Available stock quantity. minimum: 0 maximum: 9007199254740991 required: - quantity additionalProperties: false ProgramValidityDailyHours: type: object description: A single daily validity-hours window. properties: days_of_week: type: array description: Days of week the window applies to. 0 = Sunday through 6 = Saturday. items: type: integer minimum: 0 maximum: 6 start_time: type: string description: Window start time in `HH:mm` format. end_time: type: string description: Window end time in `HH:mm` format. 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 ````