Generate Random Code

Create a generic (standalone) vouchers. You can choose to create a GIFT_VOUCHER, a DISCOUNT_VOUCHER, or a LOYALTY_CARD.

When you create a new voucher, you can specify a type to create it. Creating a new voucher will create a new generic (standalone) vouchers if no campaign name or campaign_id is provided. However, if an ID or name of a campaign with the type set to STANDALONE is provided, the voucher will be added to such campaign. In case of the loyalty card, a campaign name is required.

You can optionally use the code parameter to define a specific code or the code_config parameter to design rules for Voucherify API to create a random code. If neither of the two parameters are passed, then a random code is generated by the Voucherify API.

This method will return an error when trying to create a voucher that already exists.

🚧 Standalone Vouchers and Campaigns

In version v20241004, generic (standalone) vouchers created through the Voucherify dashboard create a campaign for that voucher. However, vouchers created through the API do not have a campaign attached, so the values for campaign and campaign_id are null.

Voucherify developers work on adding an optional feature to create a generic (standalone) vouchers campaign through the API.

Follow the Voucherify Release Notes for more details about released features.

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 details of the voucher that you would like to create.

Create loyalty card with specific code

Request body schema for POST v1/vouchers.

code · string · required

Code that identifies a voucher. The pattern can use all the letters of the English alphabet, Arabic numerals, and special characters. Pass this attribute in the request body to create a distinct code. Otherwise, either use the code_config object to set the rules that the Voucherify API will use to create a random code, or don't pass any code and Voucherify will generate a random code.

Example:

"WVPblOYX"

type · enum<string> · required

Defines the type of the voucher.

Available options:

LOYALTY_CARD

loyalty_card · object · required

Simplified loyalty card data.

Show child attributes

campaign · string

Identifies the voucher's parent campaign using a unique campaign name.

Example:

"Gift Card Campaign"

campaign_id · string

Identifies the voucher's parent campaign using a unique campaign ID assigned by the Voucherify API.

Example:

"camp_FNYR4jhqZBM9xTptxDGgeNBV"

category · string

The name of the category that this voucher belongs to. Useful when listing vouchers with the List Vouchers endpoint.

category_id · string

Unique identifier assigned by Voucherify to the name of the category that this voucher belongs to. Useful when listing vouchers with the List Vouchers endpoint.

Example:

"cat_0b6152ce12414820dc"

start_date · string<date-time>

Start date defines when the code starts to be active. Activation timestamp is presented in the ISO 8601 format. Voucher is inactive before this date.

Example:

"2021-12-01T00:00:00.000Z"

expiration_date · string<date-time>

Expiration date defines when the code expires. Expiration timestamp is presented in the ISO 8601 format. Voucher is inactive after this date.

Example:

"2021-12-31T00: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

active · boolean

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

• true indicates an active voucher
• false indicates an inactive voucher

additional_info · string

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

metadata · object

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

validation_rules · string[]

Array containing the ID of the validation rule associated with the voucher.

redemption · object

Stores the quantity of redemptions that can be applied to the voucher.

Show child attributes

Response

200

application/json

Returns a voucher object if the call succeeded.

Response body schema for POST v1/vouchers and /vouchers/{code} This is an object representing a voucher with categories and validation rules assignments. This is an object representing a voucher.

id · string

Assigned by the Voucherify API, identifies the voucher.

Example:

"v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV"

code · string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example:

"WVPblOYX"

campaign · string

A unique campaign name, identifies the voucher's parent campaign.

Example:

"Gift Card Campaign"

campaign_id · string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example:

"camp_FNYR4jhqZBM9xTptxDGgeNBV"

category · string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

category_id · string

Unique category ID assigned by Voucherify.

Example:

"cat_0bb343dee3cdb5ec0c"

type · enum<string>

Defines the type of the voucher.

Available options:

GIFT_VOUCHER,

DISCOUNT_VOUCHER,

LOYALTY_CARD

discount · object

Contains information about discount.

Amount

Show child attributes

gift · object

Object representing gift parameters. Child attributes are present only if type is GIFT_VOUCHER. Defaults to null.

Show child attributes

loyalty_card · object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY_CARD. Defaults to null.

Show child attributes

start_date · string<date-time>

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

Example:

"2021-12-01T00:00:00.000Z"

expiration_date · string<date-time>

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

Example:

"2021-12-31T00: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

active · boolean | null

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

• true indicates an active voucher
• false indicates an inactive voucher

additional_info · string

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

metadata · object

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

assets · object

Stores links to images of QR and barcode that correspond to an encrypted voucher code.

Show child attributes

is_referral_code · boolean | null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL_PROGRAM.

created_at · string<date-time>

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

Example:

"2021-12-22T10:13:06.487Z"

updated_at · string<date-time>

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

Example:

"2021-12-22T10:14:45.316Z"

holder_id · string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example:

"cust_eWgXlBBiY6THFRJwX45Iakv4"

referrer_id · string

Unique identifier of the referring person.

Example:

"cust_Vzck5i8U3OhcEUFY6MKhN9Rv"

object · string · default: voucher

The type of the object represented by JSON. Default is voucher.

publish · object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Show child attributes

redemption · object

Stores a summary of redemptions that have been applied to the voucher.

Show child attributes

categories · Category · object[]

Contains details about the category.

Show child attributes

validation_rules_assignments · object

List of Validation Rules Assignments

Show child attributes