Create program

curl --request POST \
  --url {protocol}://{host}/v2/loyalties/programs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "validity_hours": {
    "daily": [
      {
        "days_of_week": [
          3
        ],
        "start_time": "09:00",
        "end_time": "17:00"
      }
    ]
  },
  "metadata": {},
  "card_definitions": [
    {
      "id": "<string>"
    }
  ],
  "earning_rules": [
    {
      "id": "<string>"
    }
  ],
  "rewards": [
    {
      "id": "<string>",
      "stock": {
        "limited": {
          "quantity": 4503599627370495
        }
      }
    }
  ],
  "tier_structures": [
    {
      "id": "<string>"
    }
  ]
}
'

{
  "id": "<string>",
  "name": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "validity_hours": {
    "daily": [
      {
        "days_of_week": [
          3
        ],
        "start_time": "<string>",
        "end_time": "<string>"
      }
    ]
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "card_definitions": [
    {
      "id": "<string>"
    }
  ],
  "earning_rules": [
    {
      "id": "<string>"
    }
  ],
  "rewards": [
    {
      "id": "<string>",
      "stock": {
        "limited": {
          "quantity": 4503599627370495
        }
      }
    }
  ],
  "tier_structures": [
    {
      "id": "<string>"
    }
  ]
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

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.

POST

loyalties

programs

Create program

curl --request POST \
  --url {protocol}://{host}/v2/loyalties/programs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "validity_hours": {
    "daily": [
      {
        "days_of_week": [
          3
        ],
        "start_time": "09:00",
        "end_time": "17:00"
      }
    ]
  },
  "metadata": {},
  "card_definitions": [
    {
      "id": "<string>"
    }
  ],
  "earning_rules": [
    {
      "id": "<string>"
    }
  ],
  "rewards": [
    {
      "id": "<string>",
      "stock": {
        "limited": {
          "quantity": 4503599627370495
        }
      }
    }
  ],
  "tier_structures": [
    {
      "id": "<string>"
    }
  ]
}
'

{
  "id": "<string>",
  "name": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "validity_hours": {
    "daily": [
      {
        "days_of_week": [
          3
        ],
        "start_time": "<string>",
        "end_time": "<string>"
      }
    ]
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "card_definitions": [
    {
      "id": "<string>"
    }
  ],
  "earning_rules": [
    {
      "id": "<string>"
    }
  ],
  "rewards": [
    {
      "id": "<string>",
      "stock": {
        "limited": {
          "quantity": 4503599627370495
        }
      }
    }
  ],
  "tier_structures": [
    {
      "id": "<string>"
    }
  ]
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id

string

header

required

X-App-Token

string

header

required

Body

application/json

Payload for creating a loyalty program.

name

string

required

Program name.

Required string length: 1 - 200

start_date

string<date-time> | null

Program validity start date, in ISO 8601 date-time format.

end_date

string<date-time> | null

Program validity end date, in ISO 8601 date-time format.

validity_hours

object | null

Validity hours configuration. Defaults to ANY_TIME when omitted.

Show child attributes

status

enum<string> | null

Initial program status. Only ACTIVE and DRAFT are allowed at creation. Defaults to DRAFT.

Available options:

ACTIVE,

DRAFT

metadata

object | null

Arbitrary key-value metadata. Validated against the vl_program metadata schema definition of the project. Defaults to {}.

card_definitions

object[] | null

Card definitions to assign at creation. Required (with active card definitions) when creating the program with status ACTIVE.

Required array length: 1 - 10 elements

Show child attributes

earning_rules

object[] | null

Earning rules to assign at creation. Required (with active earning rules) when creating the program with status ACTIVE.

Required array length: 1 - 10 elements

Show child attributes

rewards

object[] | null

Rewards to assign at creation, each with its stock configuration.

Required array length: 1 - 10 elements

Show child attributes

tier_structures

object[] | null

Tier structures to assign at creation. A program can have at most one tier structure.

Required array length: 1 - 10 elements

Show child attributes

Response

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

Program create response - the program extended with the ids of resources assigned at creation.

string

Unique program identifier.

Pattern: ^lprg_[a-f0-9]+$

name

string

Program name.

status

enum<string>

Program status.

Available options:

DRAFT,

ACTIVE,

INACTIVE,

DELETED

start_date

string<date-time> | null

Program validity start date (ISO 8601), or null when not set.

end_date

string<date-time> | null

Program validity end date (ISO 8601), or null when not set.

validity_hours

object

Validity hours configuration. Defaults to type ANY_TIME.

Show child attributes

metadata

object

Arbitrary key-value metadata. Defaults to {}.

created_at

string<date-time>

Creation timestamp (ISO 8601).

updated_at

string<date-time> | null

Last update timestamp (ISO 8601), or null when never updated.

object

string

Object type marker.

Allowed value: "program"

card_definitions

object[] | null

Card definitions assigned at creation, or null when none were provided.

Show child attributes

earning_rules

object[] | null

Earning rules assigned at creation, or null when none were provided.

Show child attributes

rewards

object[] | null

Rewards assigned at creation, or null when none were provided.

Show child attributes

tier_structures

object[] | null

Tier structures assigned at creation, or null when none were provided.

Show child attributes

Last modified on July 27, 2026

List programs Get program

⌘I

Card Definitions

Programs

Members

Examine

Earning Rules

Tier Structures

Benefits

Rewards

Create program

Authorizations

Body

Response