Redeem Promotion

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.

Path Parameters

promotionTierId

string

required

ID of the promotion tier to be redeemed.

Example:

"promo_2EnAik6Jt7dKTOMkRTIgEjZH"

Body

application/json

Provide the redemption context in the request body.

Redeem a promotion tier.

customer

Customer ID · object

Customer's information.

Customer ID
Customer Source ID
Customer

Show child attributes

customer.id

string

The ID of an existing customer that will be linked to redemption in this request.

Example:

"cust_Vzck5i8U3OhcEUFY6MKhN9Rv"

order

Order ID · object

Order information.

Order ID
Order Source ID
Orders Create Request Body

Show child attributes

order.id

string

Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.

metadata

object

A set of key/value pairs that you can send in the request body to check against promotion tiers requiring redemption metadata validation rules to be satisfied. The validation runs against rules that are defined through the Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Advanced → Redemption metadata satisfy or Basic Builder → Attributes match → REDEMPTION METADATA. Read more.

Response

Returns a redemption object if the redeem operation succeeded.

This is an object representing a promotion tier redemption.

string

Unique redemption ID.

Example:

"r_0bc92f81a6801f9bca"

object

string

default:redemption

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

date

string<date-time>

Timestamp in ISO 8601 format indicating when the redemption occured.

Example:

"2022-10-03T12:24:58.008Z"

customer_id

string

Unique customer ID of the redeeming customer.

Example:

"cust_i8t5Tt6eiKG5K79KQlJ0Vs64"

tracking_id

string

Hashed customer source ID.

Example:

"track_fxEMFiLowFHg=="

metadata

object

The metadata object stores all custom attributes in the form of key/value pairs assigned to the redemption.

result

enum<string>

Redemption result.

Available options:

SUCCESS,

FAILURE

order

Order object - Effect: Apply to order · object

Defines the details of the order that is related to the redemption.

Order object - Effect: Apply to order
Order object - Effect: Apply to items

Show child attributes

order.id

string

Unique order ID, assigned by Voucherify.

Example:

"ord_OLWs41pBk7VFn6ZTyX9U6keh"

order.source_id

string

The merchant's order ID if it is different from the Voucherify order ID. It is really useful in case of integration between multiple systems. It can be an order ID from CRM, database or 3rd party service.

order.created_at

string<date-time>

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

Example:

"2022-10-06T11:40:48.705Z"

order.updated_at

string<date-time>

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

Example:

"2022-10-06T11:47:20.760Z"

order.status

enum<string>

Order status.

Available options:

CREATED,

PAID,

CANCELED,

FULFILLED

order.amount

integer

Order amount before applying any discount.

order.discount_amount

integer

Sum of all order-level discounts applied to the order.

order.total_discount_amount

integer

Sum of all order-level AND all product-specific discounts applied to the order.
total_discount_amount = discount_amount + items_discount_amount

order.total_amount

integer

Order amount after applying all the discounts.
total_amount = amount - total_discount_amount

order.applied_discount_amount

integer

This field shows the order-level discount applied.

order.total_applied_discount_amount

integer

This field sums up all order-level and all product-specific discounts applied in a particular request.

order.items

object[]

Array of order items that have been applied to the order. Each order item can show the effects of particular discounts on the item-level.

Show child attributes

order.items.object

string

default:order_item

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

order.items.product_id

string

A unique identifier that represents the product and is assigned by Voucherify.

Example:

"prod_5h0wc453_1"

order.items.sku_id

string

A unique identifier that represents the SKU and is assigned by Voucherify.

Example:

"sku_prod_5h0wc453_1_1"

order.items.quantity

integer

Quantity of the item in the cart.

order.items.amount

integer

Represents a total pre-discount amount of order item (price * quantity).

order.items.price

integer

Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.items.subtotal_amount

integer

Final order item amount after the applied item-level discount. If there are no item-level discounts applied, this item is equal to the amount.
subtotal_amount=amount-discount_amount

order.items.product

object

This object stores more information about the related product.

Show child attributes

order.items.product.id

string

A unique identifier that represents the product and is assigned by Voucherify.

Example:

"prod_5h0wc453_1"

order.items.product.source_id

string

A unique product identifier from your inventory system.

Example:

"illy-arabica"

order.items.product.name

string

Product name.

Example:

"Brewing System"

order.items.product.price

integer

Unit price of a product. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.items.sku

object

This object stores more information about the related SKU.

Show child attributes

order.items.sku.id

string

A unique identifier that represents the SKU and is assigned by Voucherify.

Example:

"sku_prod_5h0wc453_1_1"

order.items.sku.source_id

string

A unique SKU identifier from your inventory system.

Example:

"illy-arabica-250g"

order.items.sku.sku

string

SKU name.

order.items.sku.price

integer

Unit price of a SKU. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for $100.00.

order.metadata

object

The metadata object stores all custom attributes assigned to the order. A set of key/value pairs that are att to an order object. Stores additional information about the order in a structured format.

order.customer

object

Object containing information about the customer that is making the purchase.

Show child attributes

order.customer.id

string

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

order.customer.object

string

default:customer

Type of object represented by the customer object.

order.referrer

object

Object containing information about the referrer.

Show child attributes

order.referrer.id

string

Unique referrer ID, who referred the customer making the purchase.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

order.referrer.object

string

default:customer

Type of object represented by the referrer object.

order.customer_id

string

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example:

"cust_7iUa6ICKyU6gH40dBU25kQU1"

order.referrer_id

string

Unique referrer ID.

Example:

"cust_nM4jqPiaXUvQdVSA6vTRUnix"

order.object

string

default:order

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

order.redemptions

Unstacked Redemption · object

Lists details related to the redemption.

Show child attributes

order.redemptions.redemption_ID

object

The property name is the unique redemption ID; i.e. r_0ba186c4824e4881e1. This object contains information about the redemption of an incentive.

Show child attributes

order.redemptions.redemption_ID.date

string<date-time>

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

Example:

"2022-09-02T17:06:56.649Z"

The source of the incentive.

Available options:

voucher,

promotion_tier

Unique ID of the related object that defines the incentive.

Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.

channel

object

Defines the details of the channel through which the redemption was issued.

Show child attributes

channel.channel_id

string

Unique channel ID of the user performing the redemption. This is either a user ID from a user using the Voucherify Dashboard or an X-APP-Id of a user using the API.

Example:

"user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH"

channel.channel_type

enum<string>

The source of the channel for the redemption. A USER corresponds to the Voucherify Dashboard and an API corresponds to the API.

Available options:

USER,

API

customer

object

Defines the customer that is related to the redemption.

Show child attributes

customer.id

string

The unique ID of a customer that is assigned by Voucherify.

Example:

"cust_eWgXlBBiY6THFRJwX45Iakv4"

customer.name

string

Customer's first and last name.

customer.email

string

Customer's email address.

customer.source_id

string

The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service.

customer.metadata

object

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

customer.object

string

default:customer

Type of object represented is customer.

Defines the related object.

Available options:

promotion_tier

Unique related object ID assigned by Voucherify, i.e. promo_NzjTc3ZXTe7md5SziK3uYtei for a promotion tier.

voucher

object

promotion_tier

Promotion Tier · object

Contains details of the promotion tier and the parent campaign.

Show child attributes

promotion_tier.id

string

Unique promotion tier ID.

Example:

"promo_63fYCt81Aw0h7lzyRkrGZh9p"

promotion_tier.created_at

string<date-time>

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

Example:

"2021-12-15T11:34:01.333Z"

promotion_tier.updated_at

string<date-time>

Timestamp representing the date and time when the promotion tier was updated. The value is shown in the ISO 8601 format.

Example:

"2022-02-09T09:20:05.603Z"

promotion_tier.name

string

Name of the promotion tier.

promotion_tier.banner

string

Text to be displayed to your customers on your website.

promotion_tier.action

object

Contains details about the discount applied by the promotion tier.

Show child attributes

promotion_tier.action.discount

Discount · object

Contains information about discount.

Discount
Discount
Discount
Discount
Discount

Show child attributes

promotion_tier.action.discount.type

enum<string>

default:AMOUNT

required

Defines the type of the voucher.

Available options:

AMOUNT

promotion_tier.action.discount.amount_off

number

required

Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000.

promotion_tier.action.discount.amount_off_formula

string

Formula used to dynamically calculate the discount.

promotion_tier.action.discount.aggregated_amount_limit

integer

Maximum discount amount per order.

promotion_tier.action.discount.effect

enum<string>

Defines how the discount is applied to the customer's order.

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS,

APPLY_TO_ITEMS_PROPORTIONALLY,

APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY,

APPLY_TO_ITEMS_BY_QUANTITY

promotion_tier.action.discount.is_dynamic

boolean

Flag indicating whether the discount was calculated using a formula.

promotion_tier.metadata

object

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

promotion_tier.hierarchy

integer

The promotions hierarchy defines the order in which the discounts from different tiers will be applied to a customer's order. If a customer qualifies for discounts from more than one tier, discounts will be applied in the order defined in the hierarchy.

promotion_tier.promotion_id

string

Promotion unique ID.

promotion_tier.campaign

object

Contains details about promotion tier's parent campaign.

Show child attributes

promotion_tier.campaign.id

string

Unique campaign ID.

promotion_tier.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-22T00:00:00.000Z"

promotion_tier.campaign.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"

promotion_tier.campaign.validity_timeframe

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

promotion_tier.campaign.validity_timeframe.duration

string

Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.

Example:

"PT1H"

promotion_tier.campaign.validity_timeframe.interval

string

Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.

Example:

"P2D"

promotion_tier.campaign.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

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.campaign.validity_hours

Validity Hours · object

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

Show child attributes

promotion_tier.campaign.validity_hours.daily

object[]

Defines the recurring period(s) when the resource is active. The periods should not overlap.

Show child attributes

promotion_tier.campaign.validity_hours.daily.start_time

string<time>

Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.

Example:

"12:00"

promotion_tier.campaign.validity_hours.daily.days_of_week

enum<integer>[]

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

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

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.campaign.validity_hours.daily.expiration_time

string<time>

Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.

Example:

"14:00"

promotion_tier.campaign.active

boolean

A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the start_date and expiration_date using the Disable Campaign endpoint.

true indicates an active campaign
false indicates an inactive campaign

promotion_tier.campaign.category_id

string

Unique category ID that this campaign belongs to.

Example:

"cat_0b688929a2476386a6"

promotion_tier.campaign.object

string

default:campaign

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

promotion_tier.campaign_id

string

Promotion tier's parent campaign's unique ID.

promotion_tier.active

boolean

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

true indicates an active promotion tier
false indicates an inactive promotion tier

promotion_tier.start_date

string<date-time>

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example:

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

promotion_tier.expiration_date

string<date-time>

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example:

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

promotion_tier.validity_timeframe

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

promotion_tier.validity_timeframe.duration

string

Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.

Example:

"PT1H"

promotion_tier.validity_timeframe.interval

string

Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.

Example:

"P2D"

promotion_tier.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

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.validity_hours

Validity Hours · object

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

Show child attributes

promotion_tier.validity_hours.daily

object[]

Defines the recurring period(s) when the resource is active. The periods should not overlap.

Show child attributes

promotion_tier.validity_hours.daily.start_time

string<time>

Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.

Example:

"12:00"

promotion_tier.validity_hours.daily.days_of_week

enum<integer>[]

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

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

Available options:

0,

1,

2,

3,

4,

5,

6

promotion_tier.validity_hours.daily.expiration_time

string<time>

Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.

Example:

"14:00"

promotion_tier.summary

object

Contains statistics about promotion tier redemptions and orders.

Show child attributes

promotion_tier.summary.redemptions

object

Contains statistics about promotion tier redemptions.

Show child attributes

promotion_tier.summary.redemptions.total_redeemed

integer

Number of times the promotion tier was redeemed.

promotion_tier.summary.orders

object

Contains statistics about orders related to the promotion tier.

Show child attributes

promotion_tier.summary.orders.total_amount

integer

Sum of order totals.

promotion_tier.summary.orders.total_discount_amount

integer

Sum of total discount applied using the promotion tier.

promotion_tier.object

string

default:promotion_tier

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

promotion_tier.validation_rule_assignments

Validation Rule Assignments List · object

Validation Rule Assignments List

Show child attributes

promotion_tier.validation_rule_assignments.object

string

default:list

required

The type of the object represented by JSON. This object stores information about validation rule assignments.

promotion_tier.validation_rule_assignments.data_ref

string

default:data

required

Identifies the name of the JSON property that contains the array of validation rule assignments.

promotion_tier.validation_rule_assignments.data

Validation Rule Assignment · object[]

required

A dictionary that contains an array of validation rule assignments.

Show child attributes

promotion_tier.validation_rule_assignments.data.id

string

required

Validation rule assignment ID.

Example:

"asgm_74F7QZoYbUoljwQO"

promotion_tier.validation_rule_assignments.data.rule_id

string

required

Validation rule ID.

Example:

"val_4j7DCRm2IS59"

The resource ID to which the validation rule was assigned.

Example:

"v_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT"

The type of resource to which the validation rule was assigned.

Available options:

voucher,

campaign,

earning_rule,

reward_assignment,

promotion_tier,

distribution

promotion_tier.validation_rule_assignments.data.created_at

string<date-time>

required

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

Example:

"2022-02-17T08:18:15.085Z"

promotion_tier.validation_rule_assignments.data.object

enum<string>

default:validation_rules_assignment

required

The type of the object represented by the ID.

Available options:

validation_rules_assignment

promotion_tier.validation_rule_assignments.total

integer

required

Total number of validation rule assignments.

promotion_tier.category_id

string

Promotion tier category ID.

Example:

"cat_0c9da30e7116ba6bba"

promotion_tier.categories

Category · object[]

Show child attributes

promotion_tier.categories.id

string

required

Unique category ID assigned by Voucherify.

promotion_tier.categories.name

string

required

Category name.

promotion_tier.categories.hierarchy

integer

required

Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.

Required range: x >= 0

promotion_tier.categories.object

enum<string>

default:category

required

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

Available options:

category

promotion_tier.categories.created_at

string<date-time>

required

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

Example:

"2022-07-14T10:45:13.156Z"

promotion_tier.categories.updated_at

string<date-time>

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

Example:

"2022-08-16T10:52:08.094Z"

Introduction

Endpoints

Events

Authorizations

Path Parameters

Body

Response