Skip to main content

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.

Input

Resource URI

POST https://api.ebay.com/sell/marketing/v1/item_promotion

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
Content-TypestringThis header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.marketing

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard
{ /* ItemPromotion */
"name" : "string",
}

Request fields

Input container/fieldTypeDescription
applyDiscountToSingleItemOnlyboolean

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.

Occurrence: Optional

budgetAmount

This sets the budget for the CODED_COUPON promotion type. Supported values range from 100-1000000. Supported currency codes include USD, GBP, EUR, and AUD.

Note: The budget value for an active or paused promotion can not be decreased.

Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'.

Occurrence: Optional

budget.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

budget.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

couponConfigurationCouponConfiguration

The configuration of a coded coupon promotion.

Occurrence: Conditional

couponConfiguration.couponCodestring

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.

Occurrence: Conditional

couponConfiguration.couponTypeCouponTypeEnum

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.

Occurrence: Conditional

couponConfiguration.maxCouponRedemptionPerUserinteger

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.

Occurrence: Optional

descriptionstring

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

Occurrence: Conditional

discountRulesarray of DiscountRule

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.

Occurrence: Required

discountRules.discountBenefitDiscountBenefit

This container defines the promotional discount as either a monetary amount or a percentage of the sales price.

Note: When configuring promotion benefits, populate just one of the following fields in the discountBenefit container:

  • amountOffItem
  • amountOffOrder
  • percentageOffItem
  • percentageOffOrder

For volume pricing, only percentageOffOrder is applicable as a discountBenefit. Also, the first discountBenefit container in a volume pricing configuration must set percentageOffOrder to 0.

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.

Occurrence: Required

discountRules.discountBenefit.amountOffItemAmount

The monetary amount that is discounted off an item (or items) when the promotion criteria is met.

For threshold promotions, where the buyer triggers the discount, the valid values for this field are:
  5, 6, 7, 8, 9, 10, 15, 20, 25,
  30, 35, 40, 45, 50, 55, 60, 65,
  70, 75, 80, 85, 90, 95, 100, 110,
  120, 125, 150, 200, 250


For markdown promotions, the range is greater, as outlined below and detailed more precisely here:

  • $1 increments from $5 to $100
  • $5 increments from $105 to $1,000
  • $100 increments from $1,100 to $15,000

Occurrence: Optional

discountRules.discountBenefit.amountOffItem.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

discountRules.discountBenefit.amountOffItem.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

discountRules.discountBenefit.amountOffOrderAmount

Used for threshold promotions, this is the monetary amount that is discounted off an order when the promotion criteria is met. Because this field is valid only for orders, it's not a valid combination to use with markdown promotions.

Valid values for the associated amountOffOrder.value field:
  5, 6, 7, 8, 9, 10, 15, 20, 25,
  30, 35, 40, 45, 50, 55, 60, 65,
  70, 75, 80, 85, 90, 95, 100, 110,
  120, 125, 150, 200, 250

Occurrence: Optional

discountRules.discountBenefit.amountOffOrder.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

discountRules.discountBenefit.amountOffOrder.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

discountRules.discountBenefit.percentageOffItemstring

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

Occurrence: Optional

discountRules.discountBenefit.percentageOffOrderstring

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.

Occurrence: Optional

discountRules.discountSpecificationDiscountSpecification

This container defines the criteria for when the discounts of a promotion trigger, such as the minimum quantity that the buyer must purchase before the promotion kicks in. The promotional discount is applied each time the criteria defined by this container is met.

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

Important: When configuring volume pricing promotions, only minQuantity is applicable as a discountSpecification. Also, the configuration for minQuantity in a volume pricing configuration is specific. In the first discountSpecification container, set minQuantity to 1, and in the second, set minQuantity to 2. If you include a third discountRules pair, minQuantity must be set to 3, and in a fourth, it must be set to 4. Also, you must set a ruleOrder value in each discountRules container. In the first container, discountRules must be set to 1, and in each subsequent container, the value be be incremented by 1. For more, see Configuring volume pricing discounts.

Tip: see Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.

Occurrence: Required

discountRules.discountSpecification.forEachAmountAmount

The monetary amount that must be spent on promoted items before the promotional discount is applied.

Valid values for the associated forEachAmount.value field:
  5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
  50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
  85, 89, 90, 95, 99, 100, 110, 120, 125,
  149, 150, 175, 199, 200, 249, 250, 299,
  300, 350, 399, 400, 450, 499, 500

Occurrence: Optional

discountRules.discountSpecification.forEachAmount.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

discountRules.discountSpecification.forEachAmount.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

discountRules.discountSpecification.forEachQuantityinteger

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

Occurrence: Optional

discountRules.discountSpecification.minAmountAmount

Known as the "threshold amount", the minimum dollar amount that needs to be spent on promoted items in order to qualify for the promotion's discount.

Valid values for the associated minAmount.value field:
  5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
  50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
  85, 89, 90, 95, 99, 100, 110, 120,
  125, 149, 150, 175, 199, 200, 249, 250, 299,
  300, 350, 399, 400, 450, 499, 500

Occurrence: Optional

discountRules.discountSpecification.minAmount.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

discountRules.discountSpecification.minAmount.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

discountRules.discountSpecification.minQuantityinteger

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

Occurrence: Optional

discountRules.discountSpecification.numberOfDiscountedItemsinteger

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

Occurrence: Optional

discountRules.maxDiscountAmountAmount

The limit on how much a buyer can save using a CODED_COUPON promotion type. Permitted values are 1-1000. Supported currency codes include USD, GBP, EUR, and AUD.

Note: The Currency Code for 'maxDiscountAmount' must be the same as the Currency Code for 'budget'.

Occurrence: Conditional

discountRules.maxDiscountAmount.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

discountRules.maxDiscountAmount.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

discountRules.ruleOrderinteger

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.

Occurrence: Conditional

endDatestring

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.

Occurrence: Required

inventoryCriterionInventoryCriterion

A container that defines either the listing IDs or the selection rules that specify the items to include in the promotion. Listing IDs can be either eBay listing IDs or a list of the seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory.

Note: All listings in Promotions Manager promotions must support an electronic payment method.

Occurrence: Required

inventoryCriterion.inventoryCriterionTypeInventoryCriterionEnum

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.

Occurrence: Required

inventoryCriterion.inventoryItemsarray of InventoryItem

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.


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.

Occurrence: Conditional

inventoryCriterion.inventoryItems.inventoryReferenceIdstring

The unique identifier of a single-item listing or a multi-variation listing.

To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify and item ID or a SKU (if the SKU is defined in the listing)

To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.

Occurrence: Optional

inventoryCriterion.inventoryItems.inventoryReferenceTypeInventoryReferenceTypeEnum

Indicates the type of the inventoryReferenceId, which can be either INVENTORY_ITEM or INVENTORY_ITEM_GROUP.

Note: This value is not currently returned in the response.

Occurrence: Optional

inventoryCriterion.listingIdsarray of string

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.

Occurrence: Conditional

inventoryCriterion.ruleCriteriaRuleCriteria

This container defines a set of inventory selection rules for a promotion.

When defining rule criteria, you must limit item exclusions to 100 IDs when you choose from live inventory.

Required if InventoryCriterionEnum is set to INVENTORY_BY_RULE or INVENTORY_ANY.

Occurrence: Conditional

inventoryCriterion.ruleCriteria.excludeInventoryItemsarray of InventoryItem

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

Occurrence: Optional

inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceIdstring

The unique identifier of a single-item listing or a multi-variation listing.

To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify and item ID or a SKU (if the SKU is defined in the listing)

To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.

Occurrence: Optional

inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceTypeInventoryReferenceTypeEnum

Indicates the type of the inventoryReferenceId, which can be either INVENTORY_ITEM or INVENTORY_ITEM_GROUP.

Note: This value is not currently returned in the response.

Occurrence: Optional

inventoryCriterion.ruleCriteria.excludeListingIdsarray of string

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

Occurrence: Optional

inventoryCriterion.ruleCriteria.markupInventoryItemsarray of InventoryItem

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.

Occurrence: Optional

inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceIdstring

The unique identifier of a single-item listing or a multi-variation listing.

To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify and item ID or a SKU (if the SKU is defined in the listing)

To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.

Occurrence: Optional

inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceTypeInventoryReferenceTypeEnum

Indicates the type of the inventoryReferenceId, which can be either INVENTORY_ITEM or INVENTORY_ITEM_GROUP.

Note: This value is not currently returned in the response.

Occurrence: Optional

inventoryCriterion.ruleCriteria.markupListingIdsarray of string

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.

Occurrence: Optional

inventoryCriterion.ruleCriteria.selectionRulesarray of SelectionRule

The container for the rules that select the items to include in a promotion.

Required if inventoryCriterionType is set to INVENTORY_BY_RULE.

For information on using the contained fields, see Item promotions.

Occurrence: Conditional

inventoryCriterion.ruleCriteria.selectionRules.brandsarray of string

An array of product brands. For more details, see Using the selectionRules container.

Occurrence: Optional

inventoryCriterion.ruleCriteria.selectionRules.categoryIdsarray of string

This field contains an array of the associated category ID(s).

For Item promotions, a single-item array containing the category ID associated with the promotion. Required when used in an Item promotion and either specifying a selectionRules container or when inventoryCriterionType is set to INVENTORY_BY_RULE.

For Promoted Listing campaigns, an array of category ID(s) associated with the campaign.

For information on how to get category IDs, see eBay Marketplace category IDs and Seller store category IDs

Occurrence: Conditional

inventoryCriterion.ruleCriteria.selectionRules.categoryScopeCategoryScopeEnum

This enumerated value indicates if the category ID for the item is an identifier for eBay categories or for a seller's eBay store categories.

For Promoted Listing campaigns, this field includes the type of the category ID for the item(s) to be included in the campaign.

For Item promotions, this field identifies the scope for the corresponding array as eBay categories or for a seller's eBay store categories. Required when used in an Item promotion and inventoryCriterionType is set to INVENTORY_BY_RULE.

Occurrence: Conditional

inventoryCriterion.ruleCriteria.selectionRules.listingConditionIdsarray of string

A comma-separated list of unique identifiers for the conditions of listings to be included

For Promoted Listing campaigns, refer to Add items to the PLS campaign. Up to four IDs can be specified.

For Item promotions, refer to Item condition ID and name values.

Occurrence: Optional

inventoryCriterion.ruleCriteria.selectionRules.maxPriceAmount

This container sets the maximum price threshold. For more details, see Using the selectionRules container.

Occurrence: Optional

inventoryCriterion.ruleCriteria.selectionRules.maxPrice.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

inventoryCriterion.ruleCriteria.selectionRules.maxPrice.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

inventoryCriterion.ruleCriteria.selectionRules.minPriceAmount

This container sets the minimum price threshold. For more details, see Using the selectionRules container.

Occurrence: Optional

inventoryCriterion.ruleCriteria.selectionRules.minPrice.currencyCurrencyCodeEnum

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.

Occurrence: Conditional

inventoryCriterion.ruleCriteria.selectionRules.minPrice.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

marketplaceIdMarketplaceIdEnum

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

Occurrence: Required

namestring

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

Occurrence: Required

priorityPromotionPriorityEnum

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.

Occurrence: Optional

promotionImageUrlstring

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.

Occurrence: Conditional

promotionStatusPromotionStatusEnum

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.

Occurrence: Required

promotionTypePromotionTypeEnum

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

Occurrence: Conditional

startDatestring

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.

Occurrence: Required

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
LocationURL location of new item promotion.

Response payload

Response fields

Output container/fieldTypeDescription
warningsarray of ErrorDetailV3

The container for any warning error messages generated by the request. Warnings are not fatal in that they do not prevent the call from running and returning a response, but they should be reviewed to ensure your requests are returning the responses you expect.

Occurrence: Conditional

warnings.categorystring

The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:

  • Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.
  • Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors.
  • Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.

Occurrence: Conditional

warnings.domainstring

Name of the domain containing the service or application.

Occurrence: Conditional

warnings.errorIdinteger

A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of string

Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.

Occurrence: Conditional

warnings.longMessagestring

An expanded version of message that should be around 100-200 characters long, but is not required to be such.

Occurrence: Conditional

warnings.messagestring

An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.

Occurrence: Conditional

warnings.outputRefIdsarray of string

Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.

Occurrence: Conditional

warnings.parameters.namestring

Name of the entity that threw the error.

Occurrence: Conditional

warnings.parameters.valuestring

A description of the error.

Occurrence: Conditional

warnings.subdomainstring

Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain.

Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
201Created
400Bad Request
409Business Error
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
38201API_MARKETINGAPPLICATIONInternal server error encountered. If this problem persists, contact the eBay Developers Program for support.
38204API_MARKETINGREQUESTThe seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call.
38205API_MARKETINGREQUESTThe Marketplace ID is not recognized or is not eligible for promotions.
38207API_MARKETINGREQUESTThe promotion priority is invalid. Please check and try the call again.
38218API_MARKETINGREQUESTA valid entry is required for {fieldName}.
38219API_MARKETINGREQUESTZonks! The start date and time must be earlier than the end date and time.
38220API_MARKETINGREQUESTThe end date and time must be later than the current date and time.
38228API_MARKETINGREQUESTThe amount value of '{fieldName}' contains decimals, only integers are supported.
38229API_MARKETINGREQUESTThe start date and time should be later than the current date and time.
38234API_MARKETINGREQUESTHTML is not allowed in the '{fieldName}' field.
38235API_MARKETINGREQUESTInvalid input for the '{fieldName}' field. For help, see the documentation for this call.
38236API_MARKETINGREQUESTThe 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call.
38237API_MARKETINGREQUESTThe request can have only one of these fields: 'minQuantity', 'forEachQuantity', 'minAmount', or 'forEachAmount' in 'discountSpecification'. For help, see the documentation for this call.
38238API_MARKETINGREQUESTThe 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call.
38239API_MARKETINGREQUESTThe request can have only one of these fields: 'percentageOffOrder', 'amountOffOrder', 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call.
38240API_MARKETINGREQUESTInvalid input for the 'promotionStatus' field. For help, see the documentation for this call.
38241API_MARKETINGREQUESTThis discount rule combination is currently not supported. For help, see the documentation for this call.
38242API_MARKETINGREQUESTThe request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'.
38243API_MARKETINGBUSINESSThe 'minQuantity' value is invalid. This value must be an integer.
38244API_MARKETINGBUSINESSThe 'forEachQuantity' value is invalid. This value must be an integer.
38245API_MARKETINGBUSINESSThe 'minAmount' value is invalid. For help, see the documentation for this call.
38246API_MARKETINGBUSINESSThe 'forEachAmount' value is invalid. For help, see the documentation for this call.
38247API_MARKETINGBUSINESSThe 'numberOfDiscountedItems' value is invalid. This value must be an integer.
38248API_MARKETINGBUSINESSThe 'percentOffItem' value is invalid. For help, see the documentation for this call.
38249API_MARKETINGBUSINESSThe 'percentOffOrder' value is invalid. For help, see the documentation for this call.
38250API_MARKETINGBUSINESSThe 'amountOffItem' value is invalid. For help, see the documentation for this call.
38251API_MARKETINGBUSINESSThe 'amountOffOrder' value is invalid. For help, see the documentation for this call.
38253API_MARKETINGREQUESTThe data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call.
38255API_MARKETINGREQUESTThe promotion description exceeds the maximum length, which is {promoDescriptionLength}.
38256API_MARKETINGREQUESTThe promotion name exceeds the maximum length, which is {promoNameLength}.
38257API_MARKETINGREQUESTThis promotion type supports only one discount rule for the item promotion.
38260API_MARKETINGREQUESTTo update the start date of a promotion, the promotion must be in draft or scheduled state.
38261API_MARKETINGREQUESTPromotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory.
38262API_MARKETINGREQUESTYou can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems.
38265API_MARKETINGREQUESTNumber of discount items is greater than the quantity specified in 'DiscountSpecification'.
38266API_MARKETINGBUSINESSThe 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value.
38267API_MARKETINGREQUESTThe 'DiscountBenefit.amountOffOrder' field cannot be used with the 'DiscountSpecification.numberOfDiscountedItems' field. This parameter is reserved for Buy x, Get x discounts. For help, see the documentation for this call.
38268API_MARKETINGBUSINESSThe 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'.
345110API_MARKETINGREQUESTYou can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion.
345111API_MARKETINGREQUESTYou cannot specify Rules when using the Inventory by Value Criterion.
345114API_MARKETINGREQUESTA Category scope is required for the Rule. Please refer to API documentation for allowed values.
345115API_MARKETINGREQUESTAt least one Category is required. Please provide a valid input for this field and try again.
345116API_MARKETINGREQUESTYou can specify only Marketplace categories or Store categories when creating Rules.
345118API_MARKETINGREQUESTYou can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion.
345120API_MARKETINGREQUESTInvalid Item condition. Please refer to API documentation for allowed values.
345121API_MARKETINGREQUESTYou can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion.
345122API_MARKETINGREQUESTcategory ids cannot be specified with the inventory of type any.
345123API_MARKETINGREQUESTbrands cannot be specified with inventory of type any or Store.
345124API_MARKETINGREQUESTExclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory.
345125API_MARKETINGREQUESTYou cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values.
345126API_MARKETINGREQUESTYou cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values.
345127API_MARKETINGREQUESTCategory aspects are not supported in this version.
345128API_MARKETINGREQUESTThe minimum discount rules required for volume discount promotions are {numOfDiscountRules}
345129API_MARKETINGREQUESTThe 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call.
345130API_MARKETINGREQUESTYou can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion.
345131API_MARKETINGREQUESTEach 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule.
345132API_MARKETINGREQUESTThe discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call.
345133API_MARKETINGREQUESTEach 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions.
345134API_MARKETINGREQUESTThis promotionType is currently not supported. For help, see the documentation for this call.
345136API_MARKETINGREQUESTThe 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call.
345137API_MARKETINGREQUESTThe 'couponCode' data is missing for coded coupon promotions. For help, see the documentation for this call.
345138API_MARKETINGREQUESTThe 'couponCode' value is invalid. For help, see the documentation for this call.
345139API_MARKETINGREQUESTThe 'couponType' data is missing for coded coupon promotions. For help, see the documentation for this call.
345140API_MARKETINGREQUESTThe 'couponType' value is invalid. For help, see the documentation for this call.
345141API_MARKETINGREQUESTThe 'maxDiscountAmount' data is missing for coded coupon promotions. For help, see the documentation for this call.
345142API_MARKETINGREQUESTThe 'maxDiscountAmount' value is invalid. For help, see the documentation for this call.
345143API_MARKETINGREQUESTThe 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call.
345144API_MARKETINGREQUESTThe 'budget' value is invalid. For help, see the documentation for this call.
345145API_MARKETINGREQUESTA coupon with this 'couponCode' already exists. Please try a different 'couponCode'.
345146API_MARKETINGREQUESTThe 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call.
345147API_MARKETINGREQUEST'promotionType' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call.
345148API_MARKETINGREQUESTThe 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value.

Warnings

For more on warnings, plus the codes of other common warnings, see Handling errors.

CodeDomainCategoryMeaning
38226API_MARKETINGREQUESTThe listing ID must be numeric if you're using listingIds.
38227API_MARKETINGREQUESTThe listing ID is invalid.
38263API_MARKETINGREQUESTThe SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}.
38272API_MARKETINGBUSINESSThis listing is not eligible for a promotion because it's an auction-style listing.
38273API_MARKETINGBUSINESSThis listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing.
38274API_MARKETINGBUSINESSYou haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method.
38275API_MARKETINGBUSINESSThis SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if you add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label).
345112API_MARKETINGREQUESTInvalid Store category. Please refer to API documentation to source allowed values.
345113API_MARKETINGREQUESTInvalid marketplace category ID. Please refer to API documentation for the supported values.
345137API_MARKETINGREQUEST'priority' can not be set for this promotion type. For help, see the documentation for this call.
345138API_MARKETINGREQUEST'description' can not be set for this promotion type. For help, see the documentation for this call.
345139API_MARKETINGREQUEST'applyDiscountToSingleItemOnly' can not be set for this promotion type. For help, see the documentation for this call.
345140API_MARKETINGREQUEST'promotionImageUrl' can not be set for this promotion type. For help, see the documentation for this call.
345142API_MARKETINGREQUEST'applyDiscountToSingleItemOnly' is currently not supported for this Marketplace ID. For help, see the documentation for this call.
345143API_MARKETINGREQUEST'couponType' can not be set for this promotion type. For help, see the documentation for this call.
345144API_MARKETINGREQUEST'maxCouponRedemptionPerUser' can not be set for this promotion type. For help, see the documentation for this call.
345145API_MARKETINGREQUEST'maxDiscountAmount' can not be set for this promotion type. For help, see the documentation for this call.
345146API_MARKETINGREQUEST'budget' can not be set for this promotion type. For help, see the documentation for this call.
345147API_MARKETINGREQUEST'couponCode' can not be set for this promotion type. For help, see the documentation for this call.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Create a promotion using listing IDs

Creates a DRAFT Buy 1 and get 2nd one 5% off promotion using eBay listing IDs.

Input

The input for this sample is the basic information needed to create a promotion, such as name, description, and the promotionStatus. Also included are the discountRules and a list of listing IDs in the listingIds field.

POSThttps://api.ebay.com/sell/marketing/v1/item_promotion

Output

A successful call returns the HTTP status code 201 Created.

In addition, the response includes a location response header that contains the URI to the newly created promotion.

Sample 2: Create promotion using rules and exclusions

This sample creates a DRAFT Buy 1 and get 2nd one 25% off promotion using rules to choose the listings for the promotion.

Input

The input for this sample is the basic information needed to create a promotion, such as name, description, promotionStatus, etc., and the discountRules, categoryIds, minPrice, maxPrice, listingConditionIds, and ExcludeInventoryItems.

POSThttps://api.ebay.com/sell/marketing/v1/item_promotion

Output

A successful call returns the HTTP status code 201 Created.

In addition, the response includes a location response header that contains the URI to the newly created promotion. The returned URI also includes the ID to the newly created promotion.

Sample 3: Create a volume pricing promotion

Creates a volume pricing promotion where the buyer receives a larger discount when they purchase 2-to-4 items from the seller's Store. If 2 items are purchased, the discount is 5%. 3 purchased items gets a 10% discount and 4 items gets a 15% discount off the 4 items.

Input

The input for this sample contains the mandatory fields for a volume pricing promotion.

You must set the promotionType field to VOLUME_DISCOUNT and each set of discountRules must have a ruleOrder to indicate the ordering of the discounts.

This promotion applies to all the items in the Store (and not just one specific item) and because of this, inventoryCriterionType is set to INVENTORY_ANY (and listingIds is set to null).

POSThttps://api.ebay.com/sell/marketing/v1/item_promotion

Output

A successful call returns the HTTP status code 201 Created.

In addition, the response includes a location response header that contains the URI to the newly created promotion. The returned URI also includes the ID to the newly created promotion.