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

# Create program

`POST /v2/loyalties/programs`

<Info>

<Badge color="gray">Documentation in progress</Badge>

This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.

</Info>

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/revisions/69be73b5cff0/schema)