POST /item_promotion

This method creates an item promotion, where the buyer receives a discount when they meet the buying criteria that's set for the promotion. Known here as "threshold promotions", these promotions trigger when a threshold is met.

eBay highlights promoted items by placing teasers for the promoted items throughout the online buyer flows.

Discounts are specified as either a monetary amount or a percentage off the standard sales price of a listing, letting you offer deals such as "Buy 1 Get 1" and "Buy $50, get 20% off".

Volume pricing promotions increase the value of the discount as the buyer increases the quantity they purchase.

Coded Coupons provide unique codes that a buyer can use during checkout to receive a discount. The seller can specify the number of times a buyer can use the coupon and the maximum amount across all purchases that can be discounted using the coupon. The coupon code can also be made public (appearing on the seller's Offer page, search pages, the item listing, and the checkout page) or private (only on the seller's Offer page, but the seller can include the code in email and social media).

Note: Coded Coupons are currently available in the US, UK, DE, FR, IT, ES, and AU marketplaces.

There are two ways to add items to a threshold promotion:

Key-based promotions select items using either the listing IDs or inventory reference IDs of the items you want to promote. Note that if you use inventory reference IDs, you must specify both the inventoryReferenceId and the associated inventoryReferenceType of the item(s) you want to include the promotion.
Rule-based promotions select items using a list of eBay category IDs or seller Store category IDs. Rules can further constrain items in a promotion by minimum and maximum prices, brands, and item conditions.

You must create a new promotion in either a DRAFT or SCHEDULED state. Use the DRAFT state when you are initially creating a promotion and you want to be sure it's correctly configured before scheduling it to run. When you create a promotion, the promotion ID is returned in the Location response header. Use this ID to reference the promotion in subsequent requests.

Tip: Refer to the Selling Integration Guide for details and examples showing how to create and manage threshold promotions using the Promotions Manager.

For information on the eBay marketplaces that support item promotions, see Promotions Manager requirements and restrictions.

Servers

https://api.ebay.com{basePath}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`budget`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`budget.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`budget.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`description`	String	No	This is the seller-defined "tag line" for the offer, such as "Save on designer shoes." The tag line appears under the "offer-type text" that is generated for the promotion and is displayed on the offer tile that's shown on the seller's All Offers page, and on the event page for the promotion. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. The offer-type text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, "Extra 20% off when you buy 3+". Maximum length: 50 Required if you are configuring CODED_COUPON, ORDER_DISCOUNT, or MARKDOWN_SALE promotions (and not valid for VOLUME_DISCOUNT promotions).
`applyDiscountToSingleItemOnly`	Boolean	No	This flag is relevant in only when promotionType is set to `VOLUME_DISCOUNT`. For details on volume pricing promotions, see Configuring volume pricing discounts. If set to `true`, the discount is applied only when the buyer purchases multiple quantities of a single item in the promotion. Otherwise, the promotional discount applies to multiple quantities of any items in the promotion. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the promotion.
`startDate`	String	No	The date and time the promotion starts in UTC format (`yyyy-MM-ddThh:mm:ssZ`). For display purposes, convert this time into the local time of the seller.
`marketplaceId`	String	No	The eBay marketplace ID of the site where the threshold promotion is hosted. Threshold promotions are currently supported on a limited number of eBay marketplaces. Valid values: `EBAY_AU` = Australia `EBAY_DE` = Germany `EBAY_ES` = Spain `EBAY_FR` = France `EBAY_GB` = Great Britain `EBAY_IT` = Italy `EBAY_US` = United States For implementation help, refer to eBay API documentation
`promotionType`	String	No	Use this field to specify the type of the promotion you are creating. The supported types are: `CODED_COUPON` – A coupon code promotion set with createItemPromotion. `MARKDOWN_SALE` – A markdown promotion set with createItemPriceMarkdownPromotion. `ORDER_DISCOUNT` – A threshold promotion set with createItemPromotion. `VOLUME_DISCOUNT` – A volume pricing promotion set with createItemPromotion. See the Promotions Manager documentation for details. Required if you are creating a volume pricing promotion (`VOLUME_DISCOUNT`). For implementation help, refer to eBay API documentation
`inventoryCriterion`	Object	No	This type defines either the selections rules or the list of listing IDs for the promotion. The "listing IDs" are are either the seller's item IDs or the eBay listing IDs.
`inventoryCriterion.inventoryCriterionType`	String	No	Indicates how the items to include in the promotion are selected. You can include inventory by ID, using rules, or globally include all your inventory. For implementation help, refer to eBay API documentation
`inventoryCriterion.ruleCriteria`	Object	No	This type defines the fields for a set of inventory selection rules. Required: When inventoryCriterionType is set to `INVENTORY_BY_RULE` or `INVENTORY_ANY`.
`inventoryCriterion.ruleCriteria.excludeListingIds[]`	Array	No	A list of eBay listing IDs to exclude from the promotion. Note: The request can have either excludeInventoryItems or excludeListingIds but not both. Maximum: 100 parent items Maximum SKU or custom label length: 50 characters
`inventoryCriterion.ruleCriteria.selectionRules[]`	Array	No	The container for the rules that select the items to include in a promotion. Required if inventoryCriterionType is set to `INVENTORY_BY_RULE`.
`inventoryCriterion.ruleCriteria.selectionRules[].maxPrice`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`inventoryCriterion.ruleCriteria.selectionRules[].maxPrice.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`inventoryCriterion.ruleCriteria.selectionRules[].maxPrice.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`inventoryCriterion.ruleCriteria.selectionRules[].categoryIds[]`	Array	No	A list of category IDs associated with the listings to be included in the campaign. Ads are created for all the seller's items listed in the specified categories, up to a maximum of 50,000 items. The IDs can be either a list of eBay category IDs (from the site where the item is hosted), or a list of category IDs defined and used by the seller's store. eBay Marketplace category IDs To get a list of marketplace category IDs, do one of the following: Get a list of category IDs for a marketplace by adding `/sch/allcategories/all-categories` to the marketplace URL when browsing the site. For example: `http://www.ebay.com.au/sch/allcategories/all-categories` Navigate to the desired category on the host site and copy the category ID from the URL. These options are also available for the US marketplace: See Category Changes for the latest list of category IDs. Retrieve a list of category IDs using the Taxonomy API. Seller store category IDs Because store category IDs are uniquely defined and maintained by each seller, this service cannot provide a list of a seller's IDs. However, sellers can retrieve their store category IDs as follows: Go to Seller Hub > Marketing. Click Manage store categories. A list of your store categories displays. Click the All categories link displayed at the bottom of the list. A complete list of your store categories and their associated store category IDs displays.
`inventoryCriterion.ruleCriteria.selectionRules[].categoryScope`	String	No	The enumeration values returned in this field indicate if the category IDs in the corresponding categoryIds array are identifiers for eBay categories or for a seller's eBay store categories. This field is always returned if one or more category IDs are used as a filter. For implementation help, refer to eBay API documentation
`inventoryCriterion.ruleCriteria.selectionRules[].listingConditionIds[]`	Array	No	A comma-separated list of unique identifiers for the conditions of listings to be included in the campaign. Up to four IDs can be specified. This array is only returned if one or more item condition values are used as a filter. Note: Multiple listing condition IDs are mapped to the four valid values listed below. Refer to Promoted Listings Standard campaign flow for more details. Valid Values: `1000` = New `2000` = Certified Refurbished `2500` = Seller Refurbished `3000` = Used
`inventoryCriterion.ruleCriteria.selectionRules[].minPrice`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`inventoryCriterion.ruleCriteria.selectionRules[].minPrice.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`inventoryCriterion.ruleCriteria.selectionRules[].minPrice.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`inventoryCriterion.ruleCriteria.selectionRules[].brands[]`	Array	No	An array of product brands used as an inclusion filter. A product's brand is defined in a listing's item specifics. This array will be returned if one or more product brands were used as a filter.
`inventoryCriterion.ruleCriteria.markupListingIds[]`	Array	No	A list of listing IDs to remove from a markdown promotion. The listed items are 'marked up' to their standard price after being part of the markdown promotion.
`inventoryCriterion.ruleCriteria.excludeInventoryItems[]`	Array	No	A list of seller inventory reference IDs to exclude from the promotion. Note: The request can have either excludeInventoryItems or excludeListingIds but not both. Maximum: 100 parent items Maximum SKU or custom label length: 50 characters
`inventoryCriterion.ruleCriteria.excludeInventoryItems[].inventoryReferenceId`	String	No	The seller's inventory reference ID for a listing. Also known as the "SKU" or "custom label," an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing.
`inventoryCriterion.ruleCriteria.markupInventoryItems[]`	Array	No	A list of SKUs to remove from a markdown promotion. The listed SKUs are 'marked up' to their standard price after being part of the markdown promotion.
`inventoryCriterion.ruleCriteria.markupInventoryItems[].inventoryReferenceId`	String	No	The seller's inventory reference ID for a listing. Also known as the "SKU" or "custom label," an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing.
`inventoryCriterion.inventoryItems[]`	Array	No	An array of containers for the seller's inventory reference IDs (also known as an "SKU" or "custom label") to be added to the promotion. Note: The request can have either inventoryItems or listingIds, but not both. Required: All listings in a promotion must offer an electronic payment method. Maximum: 500 parent items Maximum SKU or custom label length: 50 characters Required if InventoryCriterionType is set to `INVENTORY_BY_VALUE`, you must specify either inventoryItems or listingIds.
`inventoryCriterion.inventoryItems[].inventoryReferenceId`	String	No	The seller's inventory reference ID for a listing. Also known as the "SKU" or "custom label," an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing.
`inventoryCriterion.listingIds[]`	Array	No	An array of eBay listing IDs to be added to the promotion. Note: The request can have either inventoryItems or listingIds, but not both. Required: All listings in a promotion must offer an electronic payment method. Maximum: 500 parent items Maximum SKU or custom label length: 50 characters Required if InventoryCriterionType is set to `INVENTORY_BY_VALUE`, you must specify either inventoryItems or listingIds.
`promotionStatus`	String	No	The current status of the promotion. When creating a new promotion, this value must be set to either `DRAFT` or `SCHEDULED`. Note that you must set this value to `SCHEDULED` when you update a RUNNING promotion. For implementation help, refer to eBay API documentation
`priority`	String	No	Applicable for only ORDER_DISCOUNT promotions, this field indicates the precedence of the promotion, which is used to determine the position of a promotion on the seller's All Offers page. If an item is associated with multiple promotions, the promotion with the higher priority takes precedence. For implementation help, refer to eBay API documentation
`endDate`	String	No	The date and time the promotion ends in UTC format (`yyyy-MM-ddThh:mm:ssZ`). For display purposes, convert this time into the local time of the seller.
`name`	String	No	The seller-defined name or "title" of the promotion that the seller can use to identify a promotion. This label is not displayed in end-user flows. Maximum length: 90
`discountRules[]`	Array	No	This container defines a promotion using the following two required fields: discountBenefit – Defines a discount as either a monetary amount or a percentage that is subtracted from the sales price of an item, a set of items, or an order. discountSpecification – Defines a set of rules that determine when the promotion is applied. Note: For volume pricing, you must specify at least two and not more than four discountBenefit/discountSpecification pairs. In addition, you must define each set of rules with a ruleOrder value that corresponds with the order of volume discounts you present. Tip: Refer to Specifying item promotion discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
`discountRules[].discountSpecification`	Object	No	This container defines the criteria for when the discounts of a promotion trigger, such as the minimum quantity the buyer must purchase before the promotion kicks in. The promotional discount is applied each time the criteria defined by this container is met. Note: When configuring the rules that govern when the discounts are applied, populate just one of the following fields in the discountSpecification container: minAmount minQuantity forEachQuantity forEachAmount Tip: Refer to Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
`discountRules[].discountSpecification.minAmount`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`discountRules[].discountSpecification.minAmount.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`discountRules[].discountSpecification.minAmount.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`discountRules[].discountSpecification.forEachQuantity`	Integer	No	The number of items that must be purchased in order to qualify for the discount. Valid values: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 20, 25, 50, 75, 100`
`discountRules[].discountSpecification.minQuantity`	Integer	No	The minimum quantity of promoted items that needs to be bought in order to qualify for the promotion's discount. Valid values: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 20, 25, 50, 75, 100`
`discountRules[].discountSpecification.numberOfDiscountedItems`	Integer	No	Use this field to configure "Buy One Get One" (or BOGO) promotions. You must couple this field with forEachQuantity and an amountOffItem or percentOffItem field to configure your BOGO promotion. This field is not valid with order-based promotions. The value of this field represents the number of items to be discounted when other promotion criteria is met. For example, when the buyer adds the number of items identified by the forEachQuantity value to their cart, they are then eligible to receive the stated discount from an additional number of like items (the number of which is identified by this field) when they add those items to their cart. To receive the discount, the buyer must purchase the number of items indicated by forEachQuantity plus the number indicated by this field. Valid values: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10`
`discountRules[].discountSpecification.forEachAmount`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`discountRules[].discountSpecification.forEachAmount.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`discountRules[].discountSpecification.forEachAmount.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`discountRules[].discountBenefit`	Object	No	This container defines the promotional discount as either a monetary amount or a percentage of the sales price. Important!: You must populate one and only one of the fields in this container: amountOffItem amountOffOrder percentageOffItem percentageOffOrder Tip: Refer to Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification values to create different types of promotions.
`discountRules[].discountBenefit.percentageOffItem`	String	No	The percentage applied to the sales price that is discounted off the promoted item (or items) when the promotion criteria is met. Valid integer values for percentage off: Min: `5` Max: `80`
`discountRules[].discountBenefit.amountOffItem`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`discountRules[].discountBenefit.amountOffItem.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`discountRules[].discountBenefit.amountOffItem.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`discountRules[].discountBenefit.percentageOffOrder`	String	No	Used for threshold promotions, this is the percentage of the order price that is discounted off the order when the promotion criteria is met. This field is not value for markdown promotions. Valid integer values for ORDER_DISCOUNT promotions: Min: `5` Max: `80` For VOLUME_DISCOUNT promotions: Must be set to `0` for the first discount rule.
`discountRules[].discountBenefit.amountOffOrder`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`discountRules[].discountBenefit.amountOffOrder.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`discountRules[].discountBenefit.amountOffOrder.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`discountRules[].maxDiscountAmount`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`discountRules[].maxDiscountAmount.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`discountRules[].maxDiscountAmount.currency`	String	No	The base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is `CAD`. Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation
`discountRules[].ruleOrder`	Integer	No	This field indicates the order in which the discountRules are presented. The value specified for this field must equal the associated minQuantity value. Required if you are creating a volume pricing promotion.
`promotionImageUrl`	String	No	Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, and not valid for VOLUME_DISCOUNT promotions. Populate this field with a URL that points to an image to be used with the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size.
`couponConfiguration`	Object	No	This container defines a coded coupon promotion. It is required if the promotion type is CODED_COUPON.
`couponConfiguration.couponType`	String	No	This indicates the type of Coded Coupon promotion, and is required when the promotion type is CODED_COUPON. Supported types: PRIVATE_SINGLE_SELLER_COUPON: Anyone can use and share the coupon code, but it isn't posted on eBay. PUBLIC_SINGLE_SELLER_COUPON: Anyone can find the coupon code on eBay and use it. For implementation help, refer to eBay API documentation
`couponConfiguration.couponCode`	String	No	A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay. The code must be from 8-15 alphanumeric characters and can contain no more than two dashes ( - ). This is required when the promotion type is CODED_COUPON.
`couponConfiguration.maxCouponRedemptionPerUser`	Integer	No	This sets the limit on the number of times a buyer can use this coupon. The range of values is 1-10. If no value is provided, a buyer can use the coupon an unlimited number of times.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.