Configuring threshold discounts

Use the createItemPromotion method to create and configure threshold discounts, where the specified discounts are subtracted from the sales price of an item, a set of items, or a customer order once the buyer meets the threshold specified by the discount (such as "Buy 1"). Threshold discounts are a popular type of promotion because they produce a high rate of sales conversions.

Tip: Refer to Examples of threshold discounts to see how to configure different versions of discounts.

Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.

You can configure the following types of discounts:

Spend Offer – Created and maintained with the methods in the item_promotion resource, these straightforward offers trigger when a buyer purchases more than a specific monetary amount from the set of discounted listings.

Sellers can configure Spend Offer discounts to subtract either (1) a percentage of the sales price or (2) a monetary amount from the transaction price when the buyer reaches the spend threshold.
Quantity Offer – Much like Spend Offer discounts, Quantity Offer discounts trigger when a buyer purchases more than the specified number of items from the set of discounted items.
Volume Pricing – A subset of quantity offer discounts, "the more you buy the more you save" discounts offer larger discounts when a buyer purchases multiple quantities of a single item, or multiple items from the set of items being promoted by the seller.
Buy One Get One (BOGO) – BOGO discounts trigger when a buyer purchases a specified number of a discounted item. When the promotion triggers, the buyer receives a discount on one or more additional like items.
No Minimum – Included here for completeness, this simplest type of discount is specifically not a threshold discount. To earn the discount, all the buyer needs to do is purchase the discounted item.

Known as item price markdown discounts, or markdown discounts for short, create and maintain these discounts with the methods in the item_price_markdown resource.

Note: Sellers can also set up discounts using Discounts Manager app on Seller Hub.

Currently, Discounts Manager app supports a wider range of discounts types than does the Marketing API. However, the discounts supported by the Marketing API are the most commonly-used discount type, and we continue to expand the functionality of API with new features. Currently not supported by the Marketing API are coupon discounts, shipping discounts, and sales-event promotions. Please continue to use the web flow for these discount types.

The discountBenefit and discountSpecification fields in createItemPromotion set up (1) the discount amount and (2) when the discount triggers.

The discountBenefit container

Use discountBenefit to set the percentage or monetary amount of the discount. Configure one, and only one, of the following fields in each discount you create:

amountOffItem – An amount discounted off the item
percentageOffItem – A percentage discounted off the sales price of the item
amountOffOrder – An amount discounted off an order (a single transaction)
percentageOffOrder – A percentage discounted off the order price

Important! eBay specifies a set of monetary amounts and percentages that sellers can offer for each discount, and sellers must adhere to these preset values when configuring their discounts.

The discountSpecification container

Use discountSpecification to define the rules for when a discount is applied. Configure one, and only one, of the following fields in each discount you create:

minAmount – The minimum monetary amount, or "threshold" the buyer must spend to trigger the discount
forEachAmount – The discount triggers each time the buyer purchases the specified monetary amount
minQuantity – The minimum number of items the buyer must purchase to trigger the discount
forEachQuantity – The discount triggers each time the buyer purchases the specified quantity of items

The field numberOfDiscountedItems in the discountSpecification container is special in that it is the one field that can be combined with other fields in the container. This field is used in BOGO discounts and indicates number of items that get the discount when triggered.

In general, a discounts specifies a minimum quantity or monetary amount that must be purchased before the discount is applied. You can also specify how many items receive the discount once the minimum levels have been met.

Allowed combinations for discountBenefit and discountSpecification

At a glance, it seems as if there's unlimited ways to combine the fields in discountBenefit and discountSpecification to create discounts. There are some combinations, however, that are not supported.

The table below outlines the field combinations you can use, where you configure just one field from discountBenefit and discountSpecification each. Combining the fields in ways not represented in the table can result in invalid discounts.

Valid Combinations of discountBenefit and discountSpecification fields
		discountSpecification (use only one in any discountSpecification container)
		minAmount	forEachAmount	minQuantity	forEachQuantity
discountBenefit (use only one in any discountBenefit container)	amountOffItem			✔	✔
	amountOffOrder	✔	✔	✔	✔
	percentageOffItem			✔	✔
	percentageOffOrder	✔	✔	✔	✔

Setting up BOGO offers

Use the numberOfDiscountedItems field to create Buy One Get One (or "BOGO") discounts. To create a BOGO offer, populate numberOfDiscountedItems with any of the combinations shown for percentageOffItem in the table above.

For more, see Examples of threshold discounts.