Skip to main content

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.

warning

Be careful when combining a promotion and a sale. For more information, see common promotion errors.

Items in your promotions​

  • An item can be part of only 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 part of a promotion and a sale (for example, the promotional item also has a sale_price), the promotion and the sale_price are stacked or cumulative.
  • Unlike the cost_price_per_unit and sale_price fields, Instacart doesn't apply markup to special promotion prices.

Promotion start and end dates​

  • Ensure that the start and end dates specify a valid time period.
  • The promotion_end_at date must be later than the current date.
  • The promotion_start_at date must be earlier than the promotion_end_at date.
  • 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_at, promotion_end_at, 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.

warning

To ensure that promotions display on your storefront as expected, always use a unique promotion_group_id for each promotion. Reusing IDs can prevent your data from being ingested into our system when the previous promotion hasn't yet expired. Also, we recommend specifying the entire date range to indicate a promotion's duration.

In the following example, two items are part of the same promotion group 1234, which is a Buy 3 or more items and get $2 off each promotion:

retailer_reference_code|promotion_group_id|promotion_type|promotion_start_at|promotion_end_at|promotion_metadata
7766112321|1234|Buy_M_Or_More_Get_X_Dollars_Off_Each|2024-10-23|2024-11-27|"{""buy"":3,""discount_per_unit"":2}"
7766115474|1234|Buy_M_Or_More_Get_X_Dollars_Off_Each|2024-10-23|2024-11-27|"{""buy"":3,""discount_per_unit"":2}"

Every item in your promotion group must be available.

Columns​

ColumnData typeDescriptionExamples
promotion_typetextThe 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_Off
Buy_M_Get_X_Pct_Off
Buy_M_For_X_Dollars
Buy_M_Get_N_For_X_Dollars
Buy_M_Dollars_Get_X_Dollars_Off
promotion_group_idtextA 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_atdate (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_atdate (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_metadataJSONThe 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}.

Sample CSV file​

Download sample CSV file

Last updated on