> ## 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
>
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may be subject to change. If you want to share feedback or improvements, contact [Voucherify support](https://www.voucherify.io/contact-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:
- 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:
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 be
subject to change. If you want to share feedback or improvements,
contact [Voucherify support](https://www.voucherify.io/contact-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: 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.
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:
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
````