Timestamp representing the date and time when the promotion tier was created in ISO 8601 format.
2021-12-15T11:34:01.333Z
updated_at
Timestamp representing the date and time when the promotion tier was updated in ISO 8601 format.
2022-02-09T09:20:05.603Z
name
Name of the promotion tier.
banner
Text to be displayed to your customers on your website.
action
Contains details about the discount applied by the promotion tier.
Attributes
Description
Example
discount
The type of discount that will be applied to a customer's order.
Any of:
Amount
Attributes
Description
Example
type
Applies an amount discount.
amount_off
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. In case of the amount being calculated by the formula, i.e. the amount_off_formula parameter is present in the amount definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the amount off.
100
amount_off_formula
Formula used to calculate the discount.
effect
Defines how the discount is applied to the customer's order
Available values: APPLY_TO_ORDER, APPLY_TO_ITEMS, APPLY_TO_ITEMS_PROPORTIONALLY, APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY, APPLY_TO_ITEMS_BY_QUANTITY
Percentage
Attributes
Description
Example
type
Applies a percentage discount.
amount_limit
Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600.
percent_off
Percent taken off the subtotal amount. In case of the percent being calculated by the formula, i.e. the percent_off_formula parameter is present in the percent definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the percent off.
percent_off_formula
Formula used to calculate the discount.
effect
Defines how the discount is applied to the customer's order.
Available values: APPLY_TO_ORDER, APPLY_TO_ITEMS
Fixed
Attributes
Description
Example
type
Sets a fixed total on cart or item(s) and then calculates the discount to apply.
fixed_amount
Set a fixed valued for an order total or price of an item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. In case of the fixed amount being calculated by the formula, i.e. the fixed_amount_formula parameter is present in the fixed amount definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value.
1000
fixed_amount_formula
Formula used to calculate the discounted price of an item or a new order total.
effect
Effect
Definition
APPLY_TO_ORDER
Sets the order total amount to the value of the fixed amount. The discount value is calculated dynamically during the redemption as it's a difference between the total amount of the customer's order and the fixed amount. For example, if the fixed amount is set to equal $10 and the order amount equals $25, then the calculated discount will be $15.
APPLY_TO_ITEMS
Sets a new price on items. The total discount amount is dynamically calculated during the redemption and it's a difference between the initial item price and the fixed amount. During the redemption, prices for items will change only if the new price is lower than the original price. If the new product price you set is different from the product price in a collection, then the new product price will be passed during the redemption. If a prodct is in more than one collection, the price is always changed to the lowest price. The new price for products with several SKUs will force the price change for SKUs if their original price is higher than the new price.
Available values: APPLY_TO_ORDER, APPLY_TO_ITEMS
Unit, single item
Attributes
Description
Example
type
Applies a full value discount to item(s).
unit_off
Number of units to be granted a full value discount. In case of the unit being calculated by the formula, i.e. the unit_off_formula parameter is present in the unit definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the unit value.
1
unit_off_formula
Formula used to calculate the number of units.
unit_type
The product deemed as free, chosen from the product inventory (e.g. time, items).
prod_f1r5Tpr0DuC7
effect
Defines how the unit is added to the customer's order.
Available values: ADD_NEW_ITEMS, ADD_MISSING_ITEMS
Unit, multiple items
Attributes
Description
Example
type
Applies a full value discount to item(s).
effect
Defines the effect for adding multiple item types.
units
Array of objects defining items to be offered for free. Each item type can have a different discount effect assigned.
Array of:
Attributes
Description
Example
unit_off
Number of units to be granted a full value discount. In case of the unit being calculated by the formula, i.e. the unit_off_formula parameter is present in the unit definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the unit value.
1
unit_off_formula
Formula used to calculate the number of units.
unit_type
The product deemed as free, chosen from the product inventory (e.g. time, items).
prod_f1r5Tpr0DuC7
effect
Defines how the unit is added to the customer's order.
Available values: ADD_NEW_ITEMS, ADD_MISSING_ITEMS
Shipping
Attributes
Description
Example
type
Applies a full value discount to item(s).
unit_off
Subtracts 1 shipping item from the subtotal.
unit_type
The shipping product deemed as free.
effect
Defines how the unit is added to the customer's order.
metadata
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.
hierarchy
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.
campaign
Contains details about promotion tier's parent campaign.
Attributes
Description
Example
id
Unique campaign ID.
start_date
Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date.
2022-09-22T00:00:00.000Z
expiration_date
Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date.
2022-09-30T00:00:00.000Z
validity_timeframe
Recurrent time periods when the campaign is valid. For example, valid for 1 hour every other day.
Attributes
Description
Example
interval
Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, a campaign with an interval of P2D will be active every other day.
duration
Defines the amount of time the campaign will be active in ISO 8601 format. For example, a campaign with a duration of P1D will be valid for a duration of one day.
validity_day_of_week
Integer array corresponding to the particular days of the week in which the campaign is valid.
0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday
active
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
category_id
Unique category ID that this campaign belongs to.
cat_0b688929a2476386a6
object
The type of object represented by the campaign object. This object stores information about the campaign.
campaign_id
Promotion tier's parent campaign's unique ID.
active
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
start_date
Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.
2022-09-23T00:00:00.000Z
expiration_date
Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.
2022-09-26T00:00:00.000Z
validity_timeframe
Set recurrent time periods when the promotion tier is valid. For example, valid for 1 hour every other day.start_daterequired when including the validity_timeframe.
Attributes
Description
Example
interval
Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, a promotion tier with an interval of P2D will be active every other day.
duration
Defines the amount of time the promotion tier will be active in ISO 8601 format. For example, a promotion tier with a duration of P1D will be valid for a duration of one day.
validity_day_of_week
Integer array corresponding to the particular days of the week in which the promotion tier is valid.
0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday
summary
Contains statistics about promotion tier redemptions and orders.
Attributes
Description
Example
redemptions
Contains statistics about promotion tier redemptions.
Attributes
Description
Example
total_redeemed
Number of times the promotion tier was redeemed.
orders
Contains statistics about orders related to the promotion tier.
Attributes
Description
Example
total_amount
Sum of order totals.
total_discount_amount
Sum of total discount applied using the promotion tier.
object
The type of object represented by JSON. This object stores information about the promotion tier.
validation_rule_assignments
category_id
Promotion tier category ID.
cat_0c9da30e7116ba6bba
categories
Details about the category assigned to the promotion tier.
Language
URL
Click Try It! to start a request and see the response here!
