Create Loyalty Campaign

Creates a batch of <!-- [loyalty cards](OpenAPI.json/components/schemas/8_obj_loyalty_card_object) -->[loyalty cards](ref:get-member) aggregated in a single loyalty campaign. It also allows you to define a custom codes pattern. <!-- theme: info --> > 📘 Global uniqueness > All codes are unique across the whole project. Voucherify won't allow to generate the same codes in any of your campaigns. <!-- theme: warning --> > 🚧 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](OpenAPI.json/components/schemas/8_obj_loyalty_campaign_object) -->[loyalty campaign object](ref:get-loyalty-program) description.

Authorizations

X-App-Id · string · header · required

X-App-Token · string · header · required

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Specify the loyalty campaign details.

Request body schema for POST /loyalties. Base body schema for creating a campaign Body schema for creating a campaign of loyalty type using POST v1/campaigns.

name · string

Campaign name.

description · string

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

type · enum<string>

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

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

Available options:

AUTO_UPDATE,

STATIC

join_once · boolean

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_join · boolean

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

use_voucher_metadata_schema · boolean

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

vouchers_count · integer

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

start_date · string<date-time>

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

Example:

"2022-09-20T00:00:00.000Z"

expiration_date · string<date-time>

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

Example:

"2022-09-30T00:00:00.000Z"

validity_timeframe · object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

Show child attributes

validity_day_of_week · enum<integer>[]

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

Show child attributes

validity_hours · object

Determines the hours of validity, e.g. to create a happy hours scenario.

Show child attributes

activity_duration_after_publishing · string

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_id · string

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

Example:

"cat_0b688929a2476386a7"

category · string

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

metadata · object

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.

access_settings · object

Assigns or unassigns an area or store to the campaign.

NOTE: this object can be sent if the Areas and Stores enterprise feature is enabled. Contact Voucherify Sales to learn more.

Show child attributes

campaign_type · enum<string> · default: LOYALTY_PROGRAM

Type of campaign.

Available options:

LOYALTY_PROGRAM

voucher · object

Schema model for a discount voucher.

Show child attributes

Response

200

application/json

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

Response body schema for POST /loyalties.

id · string · required

Unique campaign ID, assigned by Voucherify.

Example:

"camp_f7fBbQxUuTN7dI7tGOo5XMDA"

name · string · required

Campaign name.

campaign_type · enum<string> · default: LOYALTY_PROGRAM · required

Type of campaign.

Available options:

LOYALTY_PROGRAM

type · enum<string> · 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

Available options:

AUTO_UPDATE,

STATIC

auto_join · boolean · required

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

join_once · boolean · 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_schema · boolean · required

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

created_at · string<date-time> · required

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

Example:

"2021-12-01T08:00:50.038Z"

creation_status · enum<string> · required

Indicates the status of the campaign creation.

Available options:

DONE,

IN_PROGRESS,

FAILED,

DRAFT,

MODIFYING

vouchers_generation_status · enum<string> · required

Indicates the status of the campaign's voucher generation.

Available options:

DONE,

IN_PROGRESS,

FAILED,

DRAFT,

MODIFYING

protected · boolean · required

Indicates whether the resource can be deleted.

category_id · string | null · required

Unique category ID that this campaign belongs to.

Example:

"cat_0b688929a2476386a7"

categories · Category · object[] · required

Contains details about the category.

Show child attributes

object · string · default: campaign · required

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

description · string

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

voucher · object

Schema model for a campaign voucher.

Show child attributes

validity_timeframe · object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

Show child attributes

validity_day_of_week · enum<integer>[]

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

Show child attributes

validity_hours · object

Determines the hours of validity, e.g. to create a happy hours scenario.

Show child attributes

activity_duration_after_publishing · string

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_count · integer

Total number of unique vouchers in campaign.

start_date · string<date-time>

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

Example:

"2022-09-20T00:00:00.000Z"

expiration_date · string<date-time>

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

Example:

"2022-09-30T00:00:00.000Z"

active · boolean

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

metadata · object

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.

updated_at · string<date-time>

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

Example:

"2022-09-20T09:18:19.623Z"

category · string

Unique category name.

readonly · boolean

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.

loyalty_tiers_expiration · object

Defines the Loyalty Tiers Expiration.

Show child attributes

validation_rules_assignments · object

List of Validation Rules Assignments

Show child attributes

access_settings_assignments · object

Lists all assignments of the campaign to areas and stores. For GET List Campaigns, this is returned if the expand=access_settings_assignments query parameter is passed in the request. This object is not returned for the GET Campaign summary endpoint.

NOTE: This object is returned only if the Areas and Stores enterprise feature is enabled. Contact Voucherify Sales to learn more.

Show child attributes