---
title: "Create program"
method: POST
path: "/v2/loyalties/programs"
tags: ["Programs"]
---

# Create program

`POST /v2/loyalties/programs`

<Warning>

<Badge color="yellow">BETA endpoint</Badge>

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](https://www.voucherify.io/contact-support) or your Technical Account Manager.

</Warning>

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.

## Request body

- ProgramCreateRequest — Payload for creating a loyalty program.
  - `name` string, required — Program name.
  - `start_date` string, date-time, nullable — Program validity start date, in ISO 8601 date-time format.
  - `end_date` string, date-time, nullable — Program validity end date, in ISO 8601 date-time format.
  - `validity_hours` ProgramValidityHoursUpsert — 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.
    - `type` 'DAILY' | 'ANY_TIME', required — Validity hours mode. `ANY_TIME` means the program is always valid; `DAILY` restricts validity to configured daily windows.
    - `daily` ProgramValidityDailyHoursUpsert[], nullable — Daily validity windows. Required when `type` is `DAILY`; must be null/omitted when `type` is `ANY_TIME`.
      - `days_of_week` integer[], required — Days of week the window applies to. 0 = Sunday through 6 = Saturday. Items must be unique.
      - `start_time` string, required — Window start time in `HH:mm` format. If seconds are provided, they are ignored.
      - `end_time` string, required — Window end time in `HH:mm` format. If seconds are provided, they are ignored.
  - `status` 'ACTIVE' | 'DRAFT', nullable — Initial program status. Only `ACTIVE` and `DRAFT` are allowed at creation. Defaults to `DRAFT`.
  - `metadata` object, nullable — Arbitrary key-value metadata. Validated against the `vl_program` metadata schema definition of the project. Defaults to `{}`.
  - `card_definitions` ProgramCardDefinitionAssignItem[], nullable — Card definitions to assign at creation. Required (with active card definitions) when creating the program with status `ACTIVE`.
    - `id` string, required — Unique card definition identifier.
  - `earning_rules` ProgramEarningRuleAssignItem[], nullable — Earning rules to assign at creation. Required (with active earning rules) when creating the program with status `ACTIVE`.
    - `id` string, required — Unique earning rule identifier.
  - `rewards` ProgramRewardAssignItem[], nullable — Rewards to assign at creation, each with its stock configuration.
    - `id` string, required — Unique reward identifier.
    - `stock` ProgramRewardAssignmentStock, required — Reward stock configuration. When `type` is `UNLIMITED`, `limited` must not be provided. When `type` is `LIMITED`, `limited` is required.
      - `type` 'UNLIMITED' | 'LIMITED', required — Stock type.
      - `limited` ProgramRewardAssignmentStockLimited — Limited stock configuration.
        - `quantity` integer, required — Available stock quantity.
  - `tier_structures` ProgramTierStructureAssignItem[], nullable — Tier structures to assign at creation. A program can have at most one tier structure.
    - `id` string, required — Unique tier structure identifier.

## Response `200`

Program created. Response includes the ids of resources assigned during creation.

- ProgramCreateResponse — A loyalty program.
  - `id` string — Unique program identifier.
  - `name` string — Program name.
  - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'DELETED' — Program status.
  - `start_date` string, date-time, nullable — Program validity start date (ISO 8601), or null when not set.
  - `end_date` string, date-time, nullable — Program validity end date (ISO 8601), or null when not set.
  - `validity_hours` ProgramValidityHours — Validity hours configuration of the program.
    - `type` 'DAILY' | 'ANY_TIME' — Validity hours mode.
    - `daily` ProgramValidityDailyHours[] — Daily validity windows. Present only when `type` is `DAILY`.
      - `days_of_week` integer[] — Days of week the window applies to. 0 = Sunday through 6 = Saturday.
      - `start_time` string — Window start time in `HH:mm` format.
      - `end_time` string — Window end time in `HH:mm` format.
  - `metadata` object — Arbitrary key-value metadata. Defaults to `{}`.
  - `created_at` string, date-time — Creation timestamp (ISO 8601).
  - `updated_at` string, date-time, nullable — Last update timestamp (ISO 8601), or null when never updated.
  - `object` 'program' — Object type marker.
  - `card_definitions` ProgramCreateAssignedCardDefinition[], nullable — Card definitions assigned at creation, or null when none were provided.
    - `id` string — Unique card definition identifier.
  - `earning_rules` ProgramCreateAssignedEarningRule[], nullable — Earning rules assigned at creation, or null when none were provided.
    - `id` string — Unique earning rule identifier.
  - `rewards` ProgramCreateAssignedReward[], nullable — Rewards assigned at creation, or null when none were provided.
    - `id` string — Unique reward identifier.
    - `stock` ProgramRewardAssignmentStock — Reward stock configuration. When `type` is `UNLIMITED`, `limited` must not be provided. When `type` is `LIMITED`, `limited` is required.
      - `type` 'UNLIMITED' | 'LIMITED', required — Stock type.
      - `limited` ProgramRewardAssignmentStockLimited — Limited stock configuration.
        - `quantity` integer, required — Available stock quantity.
  - `tier_structures` ProgramCreateAssignedTierStructure[], nullable — Tier structures assigned at creation, or null when none were provided.
    - `id` string — Unique tier structure identifier.

## Other responses

- `400` — Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state.
- `404` — Resource not found.
- `409` — Conflict - e.g. duplicate resource or invalid state transition.
- `423` — Resource locked - a related resource is in a state that prevents this operation.
- `500` — Internal server error.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/versions/f6f2f3388362/schema)