Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-263151,3912.3 MB
Loyalties

Create Loyalty Campaign

Creates a batch of loyalty cards aggregated in a single loyalty campaign. It also allows you to define a custom codes pattern.

📘 Global uniqueness All codes are unique across the whole project. Voucherify won't allow to generate the same codes in any of your campaigns.

🚧 Asynchronous action!

This is an asynchronous action, you can't read or modify a newly created campaign until the code generation is completed. See creation_status field in the loyalty campaign object description.

post/v1/loyalties

Request body

namestring

Campaign name.

descriptionstring

An optional field to keep any extra textual information about the campaign such as a campaign description and details.

type'AUTO_UPDATE' | 'STATIC' | 'STANDALONE'

Defines whether the campaign can be updated with new vouchers after campaign creation or if the campaign consists of generic (standalone) vouchers.

  • AUTO_UPDATE: the campaign is dynamic, i.e. vouchers will generate based on set criteria
  • STATIC: vouchers need to be manually published
  • STANDALONE: the campaign is a generic (standalone) one with a single voucher for public use (only for discount and gift card campaigns)
join_onceboolean

If this value is set to true, customers will be able to join the campaign only once. For loyalty campaigns, it's forced to true, even if join_once: false is passed in the request.

auto_joinboolean

Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled.

use_voucher_metadata_schemaboolean

Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema.

vouchers_countinteger

Total number of unique vouchers in campaign (size of campaign).

start_datestring date-time

Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date.

expiration_datestring date-time

Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date.

validity_day_of_weekinteger[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

  • 0 Sunday
  • 1 Monday
  • 2 Tuesday
  • 3 Wednesday
  • 4 Thursday
  • 5 Friday
  • 6 Saturday
activity_duration_after_publishingstring

Defines the amount of time the vouchers will be active after publishing. The value is shown in the ISO 8601 format. For example, a voucher with the value of P24D will be valid for a duration of 24 days.

category_idstring

Unique category ID that this campaign belongs to. Either pass this parameter OR the category.

categorystring

The category assigned to the campaign. Either pass this parameter OR the category_id.

metadataobject

The metadata object stores all custom attributes assigned to the campaign. A set of key/value pairs that you can attach to a campaign object. It can be useful for storing additional information about the campaign in a structured format.

campaign_type'LOYALTY_PROGRAM'

Type of campaign.

Example request

{
  "start_date": "2022-09-20T00:00:00.000Z",
  "expiration_date": "2022-09-30T00:00:00.000Z",
  "validity_timeframe": {
    "duration": "PT1H",
    "interval": "P2D"
  },
  "validity_hours": {
    "daily": [
      {
        "start_time": "12:00",
        "expiration_time": "14:00"
      }
    ]
  },
  "category_id": "cat_0b688929a2476386a7"
}

Response

Returns a campaign object with its settings but without the loyalty card codes.

idstring required

Unique campaign ID, assigned by Voucherify.

namestring required

Campaign name.

descriptionstring

An optional field to keep any extra textual information about the campaign such as a campaign description and details.

campaign_type'LOYALTY_PROGRAM' required

Type of campaign.

type'AUTO_UPDATE' | 'STATIC' required

Defines whether the campaign can be updated with new vouchers after campaign creation.

  • AUTO_UPDATE: the campaign is dynamic, i.e. vouchers will generate based on set criteria
  • STATIC: vouchers need to be manually published
auto_joinboolean required

Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled.

join_onceboolean required

Always set to true for loyalty campaigns, meaning customers can join the campaign only once. It can't be changed to false.

use_voucher_metadata_schemaboolean required

Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema.

validity_day_of_weekinteger[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

  • 0 Sunday
  • 1 Monday
  • 2 Tuesday
  • 3 Wednesday
  • 4 Thursday
  • 5 Friday
  • 6 Saturday
activity_duration_after_publishingstring

Defines the amount of time the campaign will be active in ISO 8601 format after publishing. For example, a campaign with a duration of P24D will be valid for a duration of 24 days.

vouchers_countinteger

Total number of unique vouchers in campaign.

start_datestring date-time

Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date.

expiration_datestring date-time

Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date.

activeboolean

A flag to toggle the campaign on or off. You can disable a campaign even though it's within the active period defined by the start_date and expiration_date.

  • true indicates an active campaign
  • false indicates an inactive campaign
metadataobject

The metadata object stores all custom attributes assigned to the campaign. A set of key/value pairs that you can attach to a campaign object. It can be useful for storing additional information about the campaign in a structured format.

created_atstring date-time required

Timestamp representing the date and time when the campaign was created. The value is shown in the ISO 8601 format.

updated_atstring date-time

Timestamp representing the date and time when the campaign was last updated in ISO 8601 format.

categorystring

Unique category name.

creation_status'DONE' | 'IN_PROGRESS' | 'FAILED' | 'DRAFT' | 'MODIFYING' required

Indicates the status of the campaign creation.

vouchers_generation_status'DONE' | 'IN_PROGRESS' | 'FAILED' | 'DRAFT' | 'MODIFYING' required

Indicates the status of the campaign's voucher generation.

readonlyboolean

Indicates whether the campaign can be only read by a restricted user in the Areas and Stores enterprise feature. It is returned only to restricted users; this field is not returned for users with other roles.

protectedboolean required

Indicates whether the resource can be deleted.

category_idstring nullable required

Unique category ID that this campaign belongs to.

objectstring required

The type of the object represented by JSON. This object stores information about the campaign.

Example response

{
  "id": "camp_f7fBbQxUuTN7dI7tGOo5XMDA",
  "voucher": {
    "start_date": "2022-09-20T00:00:00.000Z",
    "expiration_date": "2022-09-30T00:00:00.000Z",
    "validity_timeframe": {
      "duration": "PT1H",
      "interval": "P2D"
    },
    "validity_hours": {
      "daily": [
        {
          "start_time": "12:00",
          "expiration_time": "14:00"
        }
      ]
    }
  },
  "validity_timeframe": {
    "duration": "PT1H",
    "interval": "P2D"
  },
  "validity_hours": {
    "daily": [
      {
        "start_time": "12:00",
        "expiration_time": "14:00"
      }
    ]
  },
  "start_date": "2022-09-20T00:00:00.000Z",
  "expiration_date": "2022-09-30T00:00:00.000Z",
  "created_at": "2021-12-01T08:00:50.038Z",
  "updated_at": "2022-09-20T09:18:19.623Z",
  "category_id": "cat_0b688929a2476386a7",
  "categories": [
    {
      "created_at": "2022-07-14T10:45:13.156Z",
      "updated_at": "2022-08-16T10:52:08.094Z"
    }
  ],
  "validation_rules_assignments": {
    "data": [
      {
        "id": "asgm_LnY1g7UNFA9KyDrD",
        "rule_id": "val_3gPNA6SnH4ae",
        "related_object_id": "camp_CZOnEGiZfwIKWmSjhIoIT7Ol",
        "related_object_type": "campaign",
        "object": "validation_rules_assignment",
        "validation_status": "PARTIALLY_VALID",
        "validation_omitted_rules": [
          "1"
        ]
      }
    ]
  },
  "access_settings_assignments": {
    "data": [
      {
        "id": "arsca_0ef5ee192117ae2416",
        "area_id": "ar_0ea6cd7b781b8f857f",
        "area_store_id": "ars_0ec347e2016bed85f4",
        "created_at": "2024-06-25T19:04:16.260Z"
      }
    ]
  }
}