Promotion metadata fields
The promotion metadata fields determine the promotion details, such as the promotion type, the quantity required to be eligible for the discount, and the discount value.
The following table explains the valid metadata fields:
| Valid fields | Data type | Description |
|---|---|---|
bundle_price | float | Total price of items in the offer. Example: Buy 3 for $15 |
buy | integer | Number of items the customer needs to purchase to be eligible for the offer. Default value is 1.Example: Buy 2, Get 1 free |
buy_dollars | float | Minimum dollar amount the customer needs to spend to qualify for the offer. |
discount_percentage | float | Percentage discount. Example: Spend $10, Get 10% off |
discount_per_unit | integer | Dollar amount of the discount applied to each unit. Example: Buy 3 or more, Get $1 off each |
discount_value | float | Total dollar amount of the discount applied to the offer. Example: Buy 2, Get $5 off |
get | integer | Number of items received when the customer purchases this offer. Default is 1.Example: Buy 2, Get 1 free |
limit_per_order | integer | Maximum number of times a customer can qualify for the offer within a single order. Must be greater than 0. Default is no limit. |
measurement_unit | string | Measurement unit for items sold by weight. Accepted values: KG, LB, GRAM, or OZ. |
loyalty_members_only | boolean | Whether a promotion is offered to loyalty members only. 1 = True (loyalty members only) 0 = False (all customers) |
max_qty | integer | Defines the upper range for the number of units the customer needs to purchase to qualify for discounts in a multi-tier offer. Example: Buy 3, Get 10% off; Buy 6, Get 20% off |
min_qty | integer | Defines the minimum number of units the customer needs to purchase to qualify for discounts in a multi-tier offer. Example: Buy 3, Get 10% off; Buy 6, Get 20% off |
per_unit_price | string | Price per unit for a discounted item. Example: Buy 2 or more, Get each for $10 |
qty_enforced | boolean | Whether the customer must buy the number of items specified in the buy field to get the discount. Default is true.Example: Buy 2 for $3 1 = True (customer must buy at least 2 of the items) 0 = False (customer can obtain the discounted price if buying only 1 item) |
Promotional offer types and metadata examples
Instacart supports the following types of promotional offers:
| Description | promotion_type column | promotion_metadata examples | Customer experience |
|---|---|---|---|
| Buy M, Get N free Get items of equal or lesser value free when you buy M items. Sometimes known as Buy One Get One (BOGO). | Buy_M_Get_N_Free | Buy 1, get 1 free:"{""buy"":1, ""get"":1 }"Buy 3, get 2 free, loyalty members only: "{""buy"": 3, ""get"": 2, ""loyalty_members_only"" : 1}"Quantity is not enforced; customers who buy one item receive a 50% discount: "{""buy"":1, ""get"":1, ""qty_enforced"": 0}"Quantity enforced for loyalty members: "{""buy"": 3, ""get"": 2, ""loyalty_members_only"" : 1, ""qty_enforced"": 1}" |  View full image |
| Buy M, Get N for X% off Get a percentage off items of equal or lesser value when you buy M items. | Buy_M_Get_N_For_X_Pct_Off | Buy 1, get 50% off another:(""buy"": 1, ""get"": 1, ""discount_percentage"": 50.00}Buy 2, get 25% off another: (""buy"": 2, ""get"": 1, ""discount_percentage"": 25.00} |  View full image |
| Buy M, Get $X off Get dollars off the order total when you buy M items. | Buy_M_Get_X_Dollars_Off | Buy 2, get $0.50 off:"{""buy"": 2, ""discount_value"": 0.50}" |  View full image |
| Buy M, Get X% off Get a percentage off when you buy M items. | Buy_M_Get_X_Pct_Off | Buy 2, get 25% off:"{""buy"": 2, ""discount_percentage"": 25.00}" |  View full image |
| Buy M or more, Get each for $X Get items for a discounted price when you buy M or more. | Buy_M_Or_More_For_X_Dollars_Each | Buy 2 or more, get each for $10:"{""buy"":2,""per_unit_price"":10} | None available |
| Buy M or more, Get $X off each Get dollars off each item when you buy M or more. | Buy_M_Or_More_Get_X_Dollars_Off_Each | Buy 2 or more, get $2 off each:"{""buy"":2,""discount_per_unit"":2" | None available |
| Buy M or more, Get X% off Get a percentage of when you buy M or more. | Buy_M_Or_More_Get_X_Pct_Off | Buy 2 or more, get 10% off:"{""buy"": 2, ""discount_percentage"": 10.00}" | None available |
| Buy M, Get X% off Buy N, Get Y% off Get a percentage of when you buy M items and get a higher percentage off when you buy N items. | Buy_M_Get_X_Pct_Off_Tiered | Buy 3-5 units, get 10% off; Buy 6 or more units, get 20% off:"{""min_qty"":[3,6],""max_qty"":[5,10000],""discount_percentage"":[10,20]}" | None available |
| Buy M for $X Get a bundle discount price when you buy M items. | Buy_M_For_X_Dollars | Buy 2 for bundle price of $12.00:"{""buy"": 2, ""bundle_price"": 12.00}" Promotion limited to to 10 uses (10 bundles of 2) per person: "{""limit_per_order"":10,""buy"": 2, ""bundle_price"": 12.00}" |  View full image |
| Buy M, Get N for $X Get items of equal or lesser value for a discounted price when you buy M. | Buy_M_Get_N_For_X_Dollars | Buy 1, get 1 for $0.99:"{""buy"": 1, ""get"": 1, ""discount_value"": 0.99}" |  View full image |
| Spend $M, Get $X off Get dollars off the order total for every M dollars you spend. | Buy_M_Dollars_Get_X_Dollars_Off | Loyalty members get $10 off for every $45 spent on a single order. Promotion limited to 10 uses per order:"{""buy_dollars"": 45, ""discount_value"": 10.00, ""loyalty_members_only"": 1, ""limit_per_order"": 10} |  View full image |
| Buy M units, Get $X off per unit Get dollars off per unit when you buy M units. | Buy_M_Units_Get_X_Dollars_Off_Per_Measurement_Unit | Buy 3 pounds, get $3 off per pound:"{""discount_per_unit"": 3, ""measurement_unit"": ""LB"", ""buy"": 3, ""qty_enforced"": 1}"Discount is applied incrementally. For example, if the customer buys 3-5 pounds, only the first 3 pounds get the discount. If the customer buys 6 pounds, both the first 3 pounds and the second 3 pounds get the discount. | None available |
| Buy M or more units, Get $X off per unit Get dollars off per unit when you buy M or more units. | Buy_M_Units_Or_More_Get_X_Dollars_Off_Per_Measurement_Unit | Buy 3 or more pounds, get $3 off per pound:"{""discount_per_unit"": 3, ""measurement_unit"": ""LB"", ""buy"": 3, ""qty_enforced"": 1}" | None available |
| Buy M units for $X per unit Get a discount price per unit when you buy M units. | Buy_M_Units_For_X_Dollars_Per_Measurement_Unit | Buy 3 pounds, get a discount price of $3.39 per pound: "{""per_unit_price"": 3, ""measurement_unit"": ""LB"", ""buy"": 3, ""qty_enforced"": 1}"Discount is applied incrementally. For example, if a customer buys 3-5 pounds, only the first 3 pounds get the discount. If the customer buys 6 pounds, both the first 3 pounds and the second 3 pounds get the discount. | None available |
| Buy M or more units for $X per unit Get a discount price per unit when you buy M or more units. | Buy_M_Units_Or_More_For_X_Dollars_Per_Measurement_Unit | Buy 3 or more pounds for a price of $3.39 per pound:"{""per_unit_price"": 3, ""measurement_unit"": ""LB"", ""buy"": 3, ""qty_enforced"": 1}" | None available |