Promotion Tier Object

Data model description

AttributesDescriptionExample
id

Unique promotion tier ID.

promo_63fYCt81Aw0h7lzyRkrGZh9p

created_at

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.

AttributesDescriptionExample
discount

The type of discount that will be applied to a customer's order.

Any of:

Amount

AttributesDescriptionExample
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

AttributesDescriptionExample
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

AttributesDescriptionExample
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
EffectDefinition
APPLY_TO_ORDERSets 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_ITEMSSets 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

AttributesDescriptionExample
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

AttributesDescriptionExample
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:
AttributesDescriptionExample
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

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

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

AttributesDescriptionExample
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_date required when including the validity_timeframe.

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

AttributesDescriptionExample
redemptions

Contains statistics about promotion tier redemptions.

AttributesDescriptionExample
total_redeemed

Number of times the promotion tier was redeemed.

orders

Contains statistics about orders related to the promotion tier.

AttributesDescriptionExample
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!