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 |
|---|---|---|
buy | integer | Number of items purchased to be eligible for this deal. For example, Buy 2 Get 1 free (default is 1). |
get | integer | Number of items received when customer purchases this deal. For example, Buy 2 Get 1 free (default is 1). |
discount_percentage | float | The percentage discount. For example, 10.00 for 10% (default is 0%). |
discount_value | float | The dollar discount. For example, Buy 2 Get $5 Off (default is $0). |
bundle_price | float | The total price of the order. For example, Buy 3 for $15. |
limit_per_order | integer Must be > 0 | Maximum number of times a user can qualify for the promotion in a single order (default is no limit). |
loyalty_members_only | boolean | If a promotion is offered to loyalty members only, TRUE. 1 = offered to loyalty members only 0 = offered to all customers. |
qty_enforced | boolean | If quantities are enforced, TRUE. All items must be purchased and fulfilled to obtain the promotional discount. (default is 1). For example, consider the promotion Buy 2 for $3. 1 = must buy at least the amount specified in the buy field.0 = can buy 1 for $1.50 |
Promotion types and metadata examples
Instacart supports the following types of promotions:
| Description | promotion_type column | promotion_metadata examples | Customer experience |
|---|---|---|---|
| Buy 1, Get 1 Free Also known as Buy One Get One Free (BOGO). The lower-priced item is free. Note: If your BOGO offer has quantity restrictions, you must give that information to your Instacart representative. | 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 1, Get 50% Off an Item Also known as Buy One Get One 50% (BOGO50) offers. Can set a different percentage off. The lower-priced item gets the discount. | Buy_M_Get_N_For_X_Pct_Off | Buy 1, get 50% off another item:(""buy"": 1, ""get"": 1, ""discount_percentage"": 50.00}Buy 2, get 25% off another item: (""buy"": 2, ""get"": 1, ""discount_percentage"": 25.00} |  View full image |
| Buy 2, Get $0.50 Off Discount is applied to the order total. | Buy_M_Get_X_Dollars_Off | Buy 2, get $0.50 discount:"{""buy"": 2, ""discount_value"": 0.50}" |  View full image |
| Buy 2, Get 25% Off Discount is applied to each increment of two items purchased. | Buy_M_Get_X_Pct_Off | Buy 2, get 25% discount on first 2 items only:"{""buy"": 2, ""discount_percentage"": 25.00}" |  View full image |
| Buy 2 or more, Get each for $10 Discount is applied to all items once the minimum quantity is reached. | Buy_M_Or_More_For_X_Dollars_Each | Buy 2 or more, get each item for $10:"{""buy"":2,""per_unit_price"":10} | None available |
| Buy 2 or more, Get $2 off each item Discount is applied to all items once the minimum quantity is reached. | Buy_M_Or_More_Get_X_Dollars_Off_Each | Buy 2 or more, get $2 off each item:"{""buy"":2,""discount_per_unit"":2" | None available |
| Buy 2 or more, Get 10% Off Discount is applied to all items once minimum quantity is reached. | Buy_M_Or_More_Get_X_Pct_Off | Buy 2 or more, get 10% off all items:"{""buy"": 2, ""discount_percentage"": 10.00}" | None available |
| Buy 3, Get 10% Off and Buy 6 Get 20% Off The more the customer buys, the larger the discount. | Buy_M_Get_X_Pct_Off_Tiered | "{""min_qty"":[3,6],""max_qty"":[5,10000],""discount_percentage"":[10,20]}"Result:
| None available |
| Buy 2 for $12 | Buy_M_For_X_Dollars | Buy 2, get a bundle price of $12.00: "{""buy"": 2, ""bundle_price"": 12.00}" Put a limit on quantity per person: "{""limit_per_order"":10,""buy"": 2, ""bundle_price"": 12.00}" The above promotion counts towards 20 total promotion items (10 bundles of 2) |  View full image |
| Buy 1, Get 2nd For 0.99 Discount is applied to the item with the lower price. | Buy_M_Get_N_For_X_Dollars | Customer who selects only one unit doesn’t receive a discount:"{""buy"": 1, ""get"": 1, ""discount_value"": 0.99}" |  View full image |
| Buy $45, Get $10 Off | Buy_M_Dollars_Get_X_Dollars_Off | Loyalty members get $10 off for every $45 spent on a single order. Members can qualify for this promotion up to 10 times per order."{""buy_dollars"": 45, ""discount_value"": 10.00, ""loyalty_members_only"": 1, ""limit_per_order"": 10} |  View full image |