POST/item_promotion
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.
This method creates an item discount, where the buyer receives a discount when they meet the specific buying criteria. Known here as "threshold discounts", these discounts trigger when a threshold is met.
eBay highlights discounted items by placing teasers for the discounted 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 discounts 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 discount:
- Key-based discounts select items using either the listing IDs or inventory reference IDs of the items you want to discount. 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 be discounted.
- Rule-based discounts select items using a list of eBay category IDs or seller Store category IDs. Rules can further constrain the items being discounted by minimum and maximum prices, brands, and item conditions.
You must create a new discount in either a DRAFT
or SCHEDULED
state. Use the DRAFT state when you are initially creating a discount and you want to be sure it's correctly configured before scheduling it to run. When you create a discount, the promotion ID is returned in the Location response header. Use this ID to reference the discount in subsequent requests.
Tip: Refer to the Selling Integration Guide for details and examples showing how to create and manage threshold discounts using the Discounts Manager.
For information on the eBay marketplaces that support item discounts, see Discounts Manager requirements and restrictions.
Input
Resource URI
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.
Header | Type | Description |
---|---|---|
Content-Type | string | This 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 clipboardRequest fields
Input container/field | Type | Description |
---|---|---|
applyDiscountToSingleItemOnly | boolean | This flag is relevant in only when promotionType is set to Occurrence: Optional |
budget | Amount | This sets the budget for the Note: The budget value for an active or paused discount can not be decreased. Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'. Occurrence: Optional |
budget.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
budget.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
couponConfiguration | CouponConfiguration | The configuration of a coded coupon discount. Occurrence: Conditional |
couponConfiguration.couponCode | string | A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay. Occurrence: Conditional |
couponConfiguration.couponType | CouponTypeEnum | This indicates the type of Coded Coupon discount, and is required when the discount type is CODED_COUPON.
Occurrence: Conditional |
couponConfiguration.maxCouponRedemptionPerUser | integer | 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 |
description | string | This is the seller-defined "tag line" for the offer, such as "Save on designer shoes." 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 discounts (and not valid for VOLUME_DISCOUNT discounts). Occurrence: Conditional |
discountRules | array of DiscountRule | This container defines a discount using the following two required fields:
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 discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts. Occurrence: Required |
discountRules.discountBenefit | DiscountBenefit | This container defines the discount as either a monetary amount or a percentage of the sales price. Note: When configuring discount benefits, populate just one of the following fields in the discountBenefit container:
For volume pricing, only percentageOffOrder is applicable as a discountBenefit. Also, the first discountBenefit container in a volume pricing configuration must set percentageOffOrder to Tip: Refer to Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts. Occurrence: Required |
discountRules.discountBenefit.amountOffItem | Amount | The monetary amount that is discounted off an item (or items) when the discount criteria is met.
Occurrence: Optional |
discountRules.discountBenefit.amountOffItem.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
discountRules.discountBenefit.amountOffItem.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
discountRules.discountBenefit.amountOffOrder | Amount | Used for threshold discounts, this is the monetary amount that is discounted off an order when the discount criteria is met. Because this field is valid only for orders, it's not a valid combination to use with markdown discounts. Occurrence: Optional |
discountRules.discountBenefit.amountOffOrder.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
discountRules.discountBenefit.amountOffOrder.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
discountRules.discountBenefit.percentageOffItem | string | The percentage applied to the sales price that is discounted off the discounted item (or items) when the discount criteria is met. Occurrence: Optional |
discountRules.discountBenefit.percentageOffOrder | string | Used for threshold discounts, this is the percentage of the order price that is discounted off the order when the discount criteria is met. This field is not value for markdown discounts. Occurrence: Optional |
discountRules.discountSpecification | DiscountSpecification | This container defines the criteria for when the discounts trigger, such as the minimum quantity that the buyer must purchase before the discount kicks in. The 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:
Important: When configuring volume pricing discounts, 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 Tip: see Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts. Occurrence: Required |
discountRules.discountSpecification.forEachAmount | Amount | The monetary amount that must be spent on discounted items before the discount is applied. Occurrence: Optional |
discountRules.discountSpecification.forEachAmount.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
discountRules.discountSpecification.forEachAmount.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
discountRules.discountSpecification.forEachQuantity | integer | The number of items that must be purchased in order to qualify for the discount. Occurrence: Optional |
discountRules.discountSpecification.minAmount | Amount | Known as the "threshold amount", the minimum dollar amount that needs to be spent on discounted items in order to qualify for the discount. Occurrence: Optional |
discountRules.discountSpecification.minAmount.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
discountRules.discountSpecification.minAmount.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
discountRules.discountSpecification.minQuantity | integer | The minimum quantity of discounted items that needs to be bought in order to qualify for the discount. Occurrence: Optional |
discountRules.discountSpecification.numberOfDiscountedItems | integer | Use this field to configure "Buy One Get One" (or BOGO) discounts. Occurrence: Optional |
discountRules.maxDiscountAmount | Amount | The limit on how much a buyer can save using a Note: The Currency Code for 'maxDiscountAmount' must be the same as the Currency Code for 'budget'. Occurrence: Conditional |
discountRules.maxDiscountAmount.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
discountRules.maxDiscountAmount.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
discountRules.ruleOrder | integer | This field indicates the order in which the discountRules are presented. The value specified for this field must equal the associated minQuantity value. Occurrence: Conditional |
endDate | string | The date and time the discount ends in UTC format ( Occurrence: Required |
inventoryCriterion | InventoryCriterion | A container that defines either the listing IDs or the selection rules that specify the items to be discounted. 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 Discounts Manager discounts must support an electronic payment method. Occurrence: Required |
inventoryCriterion.inventoryCriterionType | InventoryCriterionEnum | Indicates how the items to be discounted are selected. You can include inventory by ID, using rules, or globally include all your inventory. Occurrence: Required |
inventoryCriterion.inventoryItems | array 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 discount. 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.inventoryReferenceId | string | The unique identifier of a single-item listing or a multi-variation listing. Occurrence: Optional |
inventoryCriterion.inventoryItems.inventoryReferenceType | InventoryReferenceTypeEnum | Indicates the type of the inventoryReferenceId, which can be either Occurrence: Optional |
inventoryCriterion.listingIds | array of string | An array of eBay listing IDs to be discounted. Note: The request can have either inventoryItems or listingIds, but not both. Required: All listings being discounted 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.ruleCriteria | RuleCriteria | This container defines a set of inventory selection rules for a discount. Occurrence: Conditional |
inventoryCriterion.ruleCriteria.excludeInventoryItems | array of InventoryItem | A list of seller inventory reference IDs to exclude from the discount. Note: The request can have either excludeInventoryItems or excludeListingIds but not both. Maximum: 100 parent itemsMaximum SKU or custom label length: 50 characters Occurrence: Optional |
inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceId | string | The unique identifier of a single-item listing or a multi-variation listing. Occurrence: Optional |
inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceType | InventoryReferenceTypeEnum | Indicates the type of the inventoryReferenceId, which can be either Occurrence: Optional |
inventoryCriterion.ruleCriteria.excludeListingIds | array of string | A list of eBay listing IDs to exclude from the discount. Note: The request can have either excludeInventoryItems or excludeListingIds but not both. Maximum: 100 parent itemsMaximum SKU or custom label length: 50 characters Occurrence: Optional |
inventoryCriterion.ruleCriteria.markupInventoryItems | array of InventoryItem | A list of SKUs to remove from a markdown discount. The listed SKUs are 'marked up' to their standard price after being part of the markdown discount. Occurrence: Optional |
inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceId | string | The unique identifier of a single-item listing or a multi-variation listing. Occurrence: Optional |
inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceType | InventoryReferenceTypeEnum | Indicates the type of the inventoryReferenceId, which can be either Occurrence: Optional |
inventoryCriterion.ruleCriteria.markupListingIds | array of string | A list of listing IDs to remove from a markdown discount. The listed items are 'marked up' to their standard price after being part of the markdown discount. Occurrence: Optional |
inventoryCriterion.ruleCriteria.selectionRules | array of SelectionRule | The container for the rules that select the items to be discounted. Occurrence: Conditional |
inventoryCriterion.ruleCriteria.selectionRules.brands | array of string | An array of product brands. For more details, see Using the selectionRules container. Occurrence: Optional |
inventoryCriterion.ruleCriteria.selectionRules.categoryIds | array of string | This field contains an array of the associated category ID(s). Occurrence: Conditional |
inventoryCriterion.ruleCriteria.selectionRules.categoryScope | CategoryScopeEnum | 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. Occurrence: Conditional |
inventoryCriterion.ruleCriteria.selectionRules.listingConditionIds | array of string | A comma-separated list of unique identifiers for the conditions of listings to be included Occurrence: Optional |
inventoryCriterion.ruleCriteria.selectionRules.maxPrice | Amount | This container sets the maximum price threshold. For more details, see Using the selectionRules container. Occurrence: Optional |
inventoryCriterion.ruleCriteria.selectionRules.maxPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
inventoryCriterion.ruleCriteria.selectionRules.maxPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
inventoryCriterion.ruleCriteria.selectionRules.minPrice | Amount | This container sets the minimum price threshold. For more details, see Using the selectionRules container. Occurrence: Optional |
inventoryCriterion.ruleCriteria.selectionRules.minPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
inventoryCriterion.ruleCriteria.selectionRules.minPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
marketplaceId | MarketplaceIdEnum | The eBay marketplace ID of the site where the threshold discount is hosted. Threshold discounts are currently supported on a limited number of eBay marketplaces. Valid values:
Occurrence: Required |
name | string | The seller-defined name or "title" of the discount that the seller can use to identify a discounts. This label is not displayed in end-user flows. Occurrence: Required |
priority | PromotionPriorityEnum | Applicable for only ORDER_DISCOUNT discounts, this field indicates the precedence of the discounts, which is used to determine the position of a discount on the seller's All Offers page. If an item is associated with multiple discounts, the discount with the higher priority takes precedence. Occurrence: Optional |
promotionImageUrl | string | Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, and not valid for VOLUME_DISCOUNT discounts. Occurrence: Conditional |
promotionStatus | PromotionStatusEnum | The current status of the discount. When creating a new discount, this value must be set to either Occurrence: Required |
promotionType | PromotionTypeEnum | Use this field to specify the type of the discount you are creating. The supported types are:
See the Discounts Manager documentation for details. Required if you are creating a volume pricing discount ( Occurrence: Conditional |
startDate | string | The date and time the discount starts in UTC format ( Occurrence: Required |
Output
HTTP response headers
See HTTP response headers for details.
Header | Meaning |
---|---|
Location | URL location of new item promotion. |
Response payload
Response fields
Output container/field | Type | Description |
---|---|---|
warnings | array 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.category | string | The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:
Occurrence: Conditional |
warnings.domain | string | Name of the domain containing the service or application. Occurrence: Conditional |
warnings.errorId | integer | 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.inputRefIds | array 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.longMessage | string | An expanded version of message that should be around 100-200 characters long, but is not required to be such. Occurrence: Conditional |
warnings.message | string | 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.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as Occurrence: Conditional |
warnings.parameters | array of ErrorParameterV3 | This optional complex field type contains a list of one or more context-specific Occurrence: Conditional |
warnings.parameters.name | string | Name of the entity that threw the error. Occurrence: Conditional |
warnings.parameters.value | string | A description of the error. Occurrence: Conditional |
warnings.subdomain | string | 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.
Status | Meaning |
---|---|
201 | Created |
400 | Bad Request |
409 | Business Error |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
38201 | API_MARKETING | APPLICATION | Internal server error encountered. If this problem persists, contact the eBay Developers Program for support. |
38204 | API_MARKETING | REQUEST | The 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. |
38205 | API_MARKETING | REQUEST | The Marketplace ID is not recognized or is not eligible for promotions. |
38207 | API_MARKETING | REQUEST | The promotion priority is invalid. Please check and try the call again. |
38218 | API_MARKETING | REQUEST | A valid entry is required for {fieldName}. |
38219 | API_MARKETING | REQUEST | Zonks! The start date and time must be earlier than the end date and time. |
38220 | API_MARKETING | REQUEST | The end date and time must be later than the current date and time. |
38228 | API_MARKETING | REQUEST | The amount value of '{fieldName}' contains decimals, only integers are supported. |
38229 | API_MARKETING | REQUEST | The start date and time should be later than the current date and time. |
38234 | API_MARKETING | REQUEST | HTML is not allowed in the '{fieldName}' field. |
38235 | API_MARKETING | REQUEST | Invalid input for the '{fieldName}' field. For help, see the documentation for this call. |
38236 | API_MARKETING | REQUEST | The 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call. |
38237 | API_MARKETING | REQUEST | The request can have only one of these fields: 'minQuantity', 'forEachQuantity', 'minAmount', or 'forEachAmount' in 'discountSpecification'. For help, see the documentation for this call. |
38238 | API_MARKETING | REQUEST | The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call. |
38239 | API_MARKETING | REQUEST | The request can have only one of these fields: 'percentageOffOrder', 'amountOffOrder', 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call. |
38240 | API_MARKETING | REQUEST | Invalid input for the 'promotionStatus' field. For help, see the documentation for this call. |
38241 | API_MARKETING | REQUEST | This discount rule combination is currently not supported. For help, see the documentation for this call. |
38242 | API_MARKETING | REQUEST | The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'. |
38243 | API_MARKETING | BUSINESS | The 'minQuantity' value is invalid. This value must be an integer. |
38244 | API_MARKETING | BUSINESS | The 'forEachQuantity' value is invalid. This value must be an integer. |
38245 | API_MARKETING | BUSINESS | The 'minAmount' value is invalid. For help, see the documentation for this call. |
38246 | API_MARKETING | BUSINESS | The 'forEachAmount' value is invalid. For help, see the documentation for this call. |
38247 | API_MARKETING | BUSINESS | The 'numberOfDiscountedItems' value is invalid. This value must be an integer. |
38248 | API_MARKETING | BUSINESS | The 'percentOffItem' value is invalid. For help, see the documentation for this call. |
38249 | API_MARKETING | BUSINESS | The 'percentOffOrder' value is invalid. For help, see the documentation for this call. |
38250 | API_MARKETING | BUSINESS | The 'amountOffItem' value is invalid. For help, see the documentation for this call. |
38251 | API_MARKETING | BUSINESS | The 'amountOffOrder' value is invalid. For help, see the documentation for this call. |
38253 | API_MARKETING | REQUEST | The data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call. |
38255 | API_MARKETING | REQUEST | The promotion description exceeds the maximum length, which is {promoDescriptionLength}. |
38256 | API_MARKETING | REQUEST | The promotion name exceeds the maximum length, which is {promoNameLength}. |
38257 | API_MARKETING | REQUEST | This promotion type supports only one discount rule for the item promotion. |
38260 | API_MARKETING | REQUEST | To update the start date of a promotion, the promotion must be in draft or scheduled state. |
38261 | API_MARKETING | REQUEST | Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory. |
38262 | API_MARKETING | REQUEST | You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems. |
38265 | API_MARKETING | REQUEST | Number of discount items is greater than the quantity specified in 'DiscountSpecification'. |
38266 | API_MARKETING | BUSINESS | The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value. |
38267 | API_MARKETING | REQUEST | The '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. |
38268 | API_MARKETING | BUSINESS | The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'. |
345110 | API_MARKETING | REQUEST | You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion. |
345111 | API_MARKETING | REQUEST | You cannot specify Rules when using the Inventory by Value Criterion. |
345114 | API_MARKETING | REQUEST | A Category scope is required for the Rule. Please refer to API documentation for allowed values. |
345115 | API_MARKETING | REQUEST | At least one Category is required. Please provide a valid input for this field and try again. |
345116 | API_MARKETING | REQUEST | You can specify only Marketplace categories or Store categories when creating Rules. |
345118 | API_MARKETING | REQUEST | You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion. |
345120 | API_MARKETING | REQUEST | Invalid Item condition. Please refer to API documentation for allowed values. |
345121 | API_MARKETING | REQUEST | You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion. |
345122 | API_MARKETING | REQUEST | category ids cannot be specified with the inventory of type any. |
345123 | API_MARKETING | REQUEST | brands cannot be specified with inventory of type any or Store. |
345124 | API_MARKETING | REQUEST | Exclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory. |
345125 | API_MARKETING | REQUEST | You 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. |
345126 | API_MARKETING | REQUEST | You 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. |
345127 | API_MARKETING | REQUEST | Category aspects are not supported in this version. |
345128 | API_MARKETING | REQUEST | The minimum discount rules required for volume discount promotions are {numOfDiscountRules} |
345129 | API_MARKETING | REQUEST | The 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call. |
345130 | API_MARKETING | REQUEST | You can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion. |
345131 | API_MARKETING | REQUEST | Each 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule. |
345132 | API_MARKETING | REQUEST | The discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call. |
345133 | API_MARKETING | REQUEST | Each 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions. |
345134 | API_MARKETING | REQUEST | This promotionType is currently not supported. For help, see the documentation for this call. |
345136 | API_MARKETING | REQUEST | The 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call. |
345137 | API_MARKETING | REQUEST | The 'couponCode' data is missing for coded coupon promotions. For help, see the documentation for this call. |
345138 | API_MARKETING | REQUEST | The 'couponCode' value is invalid. For help, see the documentation for this call. |
345139 | API_MARKETING | REQUEST | The 'couponType' data is missing for coded coupon promotions. For help, see the documentation for this call. |
345140 | API_MARKETING | REQUEST | The 'couponType' value is invalid. For help, see the documentation for this call. |
345141 | API_MARKETING | REQUEST | The 'maxDiscountAmount' data is missing for coded coupon promotions. For help, see the documentation for this call. |
345142 | API_MARKETING | REQUEST | The 'maxDiscountAmount' value is invalid. For help, see the documentation for this call. |
345143 | API_MARKETING | REQUEST | The 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call. |
345144 | API_MARKETING | REQUEST | The 'budget' value is invalid. For help, see the documentation for this call. |
345145 | API_MARKETING | REQUEST | A coupon with this 'couponCode' already exists. Please try a different 'couponCode'. |
345146 | API_MARKETING | REQUEST | The 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call. |
345147 | API_MARKETING | REQUEST | 'promotionType' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call. |
345148 | API_MARKETING | REQUEST | The 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
38226 | API_MARKETING | REQUEST | The listing ID must be numeric if you're using listingIds. |
38227 | API_MARKETING | REQUEST | The listing ID is invalid. |
38263 | API_MARKETING | REQUEST | The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}. |
38272 | API_MARKETING | BUSINESS | This listing is not eligible for a promotion because it's an auction-style listing. |
38273 | API_MARKETING | BUSINESS | This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing. |
38274 | API_MARKETING | BUSINESS | You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method. |
38275 | API_MARKETING | BUSINESS | This 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). |
345112 | API_MARKETING | REQUEST | Invalid Store category. Please refer to API documentation to source allowed values. |
345113 | API_MARKETING | REQUEST | Invalid marketplace category ID. Please refer to API documentation for the supported values. |
345137 | API_MARKETING | REQUEST | 'priority' can not be set for this promotion type. For help, see the documentation for this call. |
345138 | API_MARKETING | REQUEST | 'description' can not be set for this promotion type. For help, see the documentation for this call. |
345139 | API_MARKETING | REQUEST | 'applyDiscountToSingleItemOnly' can not be set for this promotion type. For help, see the documentation for this call. |
345140 | API_MARKETING | REQUEST | 'promotionImageUrl' can not be set for this promotion type. For help, see the documentation for this call. |
345142 | API_MARKETING | REQUEST | 'applyDiscountToSingleItemOnly' is currently not supported for this Marketplace ID. For help, see the documentation for this call. |
345143 | API_MARKETING | REQUEST | 'couponType' can not be set for this promotion type. For help, see the documentation for this call. |
345144 | API_MARKETING | REQUEST | 'maxCouponRedemptionPerUser' can not be set for this promotion type. For help, see the documentation for this call. |
345145 | API_MARKETING | REQUEST | 'maxDiscountAmount' can not be set for this promotion type. For help, see the documentation for this call. |
345146 | API_MARKETING | REQUEST | 'budget' can not be set for this promotion type. For help, see the documentation for this call. |
345147 | API_MARKETING | REQUEST | '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 discount using listing IDs
Creates a DRAFT Buy 1 and get 2nd one 5% off discount using eBay listing IDs.
Input
The input for this sample is the basic information needed to create a discount, 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 discount.
Sample 2: Create discount using rules and exclusions
This sample creates a DRAFT Buy 1 and get 2nd one 25% off discount using rules to choose the listings for the discount.
Input
The input for this sample is the basic information needed to create a discount, 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 discount. The returned URI also includes the ID to the newly created discount.
Sample 3: Create a volume pricing discount
Creates a volume pricing discount 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 discount.
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 discount 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 discount. The returned URI also includes the ID to the newly created discount.