> ## 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 loyalty 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. Optionally attaches card definitions, earning rules, rewards, and tier structures in the same request. The response uses `toCreateDTO(params)` which includes the attached resource ids alongside the program fields. ## 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 API documentation for Voucherify Loyalty v2 system. Requires LOYALTY_V2 feature flag. servers: - url: https://api.voucherify.io description: Production security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - 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: 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: 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: Incentives description: >- Manage incentive 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: Examines the earning of loyalty points for a loyalty program member. paths: /v2/loyalties/programs: post: tags: - Programs summary: Create a loyalty 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. Optionally attaches card definitions, earning rules, rewards, and tier structures in the same request. The response uses `toCreateDTO(params)` which includes the attached resource ids alongside the program fields. operationId: createProgram requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProgramCreateRequest' responses: '200': description: Program created successfully content: application/json: schema: $ref: '#/components/schemas/ProgramCreateResponse' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' components: schemas: ProgramCreateRequest: type: object required: - name properties: name: type: string minLength: 1 maxLength: 200 description: Program name status: oneOf: - $ref: '#/components/schemas/ProgramCreateStatus' - type: 'null' description: Initial status (defaults to DRAFT if not provided) start_date: type: - string - 'null' format: date-time description: Program start date (ISO 8601) end_date: type: - string - 'null' format: date-time description: Program end date (ISO 8601) metadata: oneOf: - $ref: '#/components/schemas/Metadata' - type: 'null' description: Custom metadata key-value pairs card_definitions: oneOf: - type: array items: $ref: '#/components/schemas/CardDefinitionAssignRef' minItems: 1 maxItems: 10 - type: 'null' description: Card definitions to assign on creation earning_rules: oneOf: - type: array items: $ref: '#/components/schemas/EarningRuleAssignRef' minItems: 1 maxItems: 10 - type: 'null' description: Earning rules to assign on creation rewards: oneOf: - type: array items: $ref: '#/components/schemas/RewardAssignRef' minItems: 1 maxItems: 10 - type: 'null' description: Rewards to assign on creation tier_structures: oneOf: - type: array items: $ref: '#/components/schemas/TierStructureAssignRef' minItems: 1 maxItems: 10 - type: 'null' description: Tier structures to assign on creation additionalProperties: false ProgramCreateResponse: type: object description: | Extended program DTO returned by toCreateDTO(params). Includes the program fields plus arrays of attached resource references. allOf: - $ref: '#/components/schemas/ProgramResponse' - type: object properties: card_definitions: type: - array - 'null' items: $ref: '#/components/schemas/ProgramCreateCardDefinitionRef' description: Card definitions attached during creation earning_rules: type: - array - 'null' items: $ref: '#/components/schemas/ProgramCreateEarningRuleRef' description: Earning rules attached during creation rewards: type: - array - 'null' items: $ref: '#/components/schemas/ProgramCreateRewardRef' description: Rewards attached during creation tier_structures: type: - array - 'null' items: $ref: '#/components/schemas/ProgramCreateTierStructureRef' description: Tier structures attached during creation ProgramCreateStatus: description: Status allowed at creation time type: string enum: - DRAFT - ACTIVE Metadata: type: object description: Custom key-value metadata. additionalProperties: true CardDefinitionAssignRef: type: object required: - id properties: id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Card definition id to assign additionalProperties: false EarningRuleAssignRef: type: object required: - id properties: id: type: string pattern: ^lern_[a-f0-9]+$ description: Earning rule id to assign additionalProperties: false RewardAssignRef: type: object required: - id - costs - stock properties: id: type: string pattern: ^lrew_[a-f0-9]+$ description: Reward id to assign costs: type: array items: $ref: '#/components/schemas/RewardAssignmentCostsRequest' minItems: 1 maxItems: 10 description: Cost definitions for this reward assignment stock: type: integer minimum: 0 maximum: 2147483647 description: Available stock for the reward additionalProperties: false TierStructureAssignRef: type: object required: - id properties: id: type: string pattern: ^lts_[a-f0-9]+$ description: Tier structure id to assign additionalProperties: false ProgramResponse: type: object description: Program DTO returned by toDTO() properties: id: type: string pattern: ^lprg_[a-f0-9]+$ description: Unique program identifier name: type: string description: Program name status: $ref: '#/components/schemas/ProgramStatus' start_date: type: - string - 'null' format: date-time description: Program start date end_date: type: - string - 'null' format: date-time description: Program end date metadata: $ref: '#/components/schemas/Metadata' 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) object: type: string const: program ProgramCreateCardDefinitionRef: type: object properties: id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Card definition id ProgramCreateEarningRuleRef: type: object properties: id: type: string pattern: ^lern_[a-f0-9]+$ description: Earning rule id ProgramCreateRewardRef: type: object properties: id: type: string pattern: ^lrew_[a-f0-9]+$ description: Reward id costs: type: - array - 'null' items: $ref: '#/components/schemas/RewardAssignmentCostsDTO' description: Costs associated with the reward stock: type: integer description: Available stock for the reward ProgramCreateTierStructureRef: type: object properties: id: type: string pattern: ^lts_[a-f0-9]+$ description: Tier structure id ErrorResponse: type: object description: Standard error response. properties: code: type: integer description: HTTP status code. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional error details. request_id: type: - string - 'null' description: Request identifier for tracing. resource_id: type: string description: Related resource identifier (when applicable). resource_type: type: string description: Related resource type (when applicable). required: - code - key - message RewardAssignmentCostsRequest: type: object required: - spending properties: rules: $ref: '#/components/schemas/RewardAssignmentCostsRulesRequest' spending: type: array items: $ref: '#/components/schemas/RewardAssignmentCostsSpendingRequest' minItems: 1 maxItems: 1 description: Spending definitions (currently limited to 1) additionalProperties: false ProgramStatus: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED RewardAssignmentCostsDTO: type: object properties: rules: description: >- Rule group (present only when rules are defined and have definitions) spending: type: - array - 'null' items: $ref: '#/components/schemas/RewardAssignmentSpendingDTO' RewardAssignmentCostsRulesRequest: type: object required: - logic properties: logic: type: string description: Logical formula combining rule definitions (e.g. "1 AND 2") additionalProperties: true description: > Rule group object. Keys are numeric identifiers (e.g. "1", "2") pointing to RewardRulesDefinition objects. The `logic` key defines how rules combine. RewardAssignmentCostsSpendingRequest: type: object required: - points - card_definition_id properties: points: type: integer minimum: 1 maximum: 2147483647 description: Number of points required card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Card definition to deduct points from additionalProperties: false RewardAssignmentSpendingDTO: type: object properties: points: type: integer description: Number of points required card_definition_id: type: string description: Card definition to deduct points from responses: BadRequest: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 ````