Promotion requirements
You can create complex promotions such as Buy 3 for $10 and Buy any 2 get 20% off, and apply them to your items.
Be careful when combining a promotion and a sale. For more information, see common promotion errors.
Items in your promotions
- An item can only be part of one
promotion_type. - Every item in your promotion must be available.
- Promotion updates must contain all columns related to the promotion.
- If an item is a part of a promotion and a sale (for example, the promotional item also has a
sale_price), the promotion and thesale_priceare stacked or cumulative. - Unlike the
cost_price_per_unitandsale_pricefields, no markup is applied to special promotion prices.
Promotion start and end dates
- Ensure start and end dates are for valid time periods.
- The
promotion_end_atdate must be later than the current date. - The
promotion_start_atdate must be earlier than thepromotion_end_atdate. - To end a promotion, you must enter an actual end date. You can't deactivate a promotion by leaving the end date empty.
Promotion groups
A promotion group is a collection of items that are part of the same promotion. For example, buy any two products in the promotion to get $5 off. Use the promotion_group_id column to group items together for the promotion. The value of the promotion_group_id is retailer-defined and can be any alphanumeric string.
The items in a promotion group must have the same promotion_group_id, promotion_type, promotion_start_date, promotion_end_date, and promotion_metadata. If not, the promotion is not active. For example, if three items are in a promotion and one of the items has a different end date, the entire promotion is not activated.
In the following example, two items are part of the same promotion group 1234, which is a Buy 3 items and get $2 off each promotion:
retailer_reference_code|promotion_group_id|promotion_type|promotion_start_date|promotion_end_date|promotion_metadata
7766112321|1234|Buy_M_Get_X_Dollars_Off_Each|2024-10-23|2024-11-27|"{""buy"":3,""discount_value"":2}"
7766115474|1234|Buy_M_Get_X_Dollars_Off_Each|2024-10-23|2024-11-27|"{""buy"":3,""discount_value"":2}"
Every item in your promotion group must be available.
Columns
| Column | Data type | Description | Examples |
|---|---|---|---|
promotion_type | text | The type of promotion that you want to create. Must be the same for every item in the promotion. For more information, see promotion examples. | Buy_M_Get_X_Dollars_OffBuy_M_Get_X_Pct_OffBuy_M_For_X_DollarsBuy_M_Get_N_For_X_DollarsBuy_M_Dollars_Get_X_Dollars_Off |
promotion_group_id | text | A promotion is applied to items that have the same promotion_group_id. Use this column to offer discounts across multiple products. For example, buy any two products to get $5 off. You can't define two different discounts with the same promotion_group_id. For example, you can't define a Buy 1 for $2.00 promotion and a Buy 2 for $3.00 promotion using the same promotion_group_id. | 1234 |
promotion_start_at | date (no timestamp) | Promotion start date, in the format MM/DD/YYYY (inclusive).The promotion starts at 12:01 AM Pacific Time. | 10/20/2023 |
promotion_end_at | date (no timestamp) | Promotion end date, in the format MM/DD/YYYY (exclusive). The promotion ends at 11:59 PM Pacific Time on the day prior to your specified end date. | 10/22/2017 means 10/21/2017 11:59 PM Pacific Time. |
promotion_metadata | JSON | The promotion details. For more information, see Promotion metadata. | "{""buy"":1,""get"":1 }""{""buy"":3,""discount_value"":2 }""{""buy"":3,""get"":2,""loyalty_members_only"":1 }""{""buy"":3,""discount_value"":2 }""{""buy"":3,""discount_percentage"":10.00 }" Note: When you open the CSV file in some editors, the cell might show fewer quotation marks ("), such as {"buy":3,"discount_value":2}. |