Skip to main content

Use the createItemPromotion method to create and configure threshold promotions, 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 promotion (such as "Buy 1"). Threshold promotions are a popular type of promotion because they produce a high rate of sales conversions.

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

You can configure the following types of discount promotions:

  • 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 promoted listings.

    Sellers can configure Spend Offer promotions 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 promotions, Quantity Offer promotions trigger when a buyer purchases more than the specified number of items from the set of promoted items.
  • Volume Pricing – A subset of quantity offer promotions, "the more you buy the more you save" promotions 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 promotions trigger when a buyer purchases a specified number of a promoted 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 promotion is specifically not a threshold promotion. To earn the discount, all the buyer needs to do is purchase the promoted item.

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

Note: Sellers can also set up promotions using Promotions Manager app on Seller Hub.

Currently, Promotions Manager app supports a wider range of promotions types than does the Marketing API. However, the discount promotions supported by the Marketing API are the most commonly-used promotion 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.

Configuring threshold promotions

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 promotion you create:

  • amountOffItem – An amount discounted off the promoted item
  • percentageOffItem – A percentage discounted off the sales price of the promoted 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 promotion, and sellers must adhere to these preset values when configuring their discounts.

The discountSpecification container

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

  • minAmount – The minimum monetary amount, or "threshold" the buyer must spend to trigger the promotion
  • forEachAmount – The promotion triggers each time the buyer purchases the specified monetary amount
  • minQuantity – The minimum number of items the buyer must purchase to trigger the promotion
  • forEachQuantity – The promotion triggers each time the buyer purchases the specified quantity of promoted 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 promotions and indicates number of items that get the discount when the promotion triggers.

In general, a promotion 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 promotional 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 promotional discounts.

Valid Combinations of discountBenefit and discountSpecification fields


(use only one in any discountSpecification container)






(use only one in any
discountBenefit container)









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 promotions.