PUT/item_price_markdown/{promotion_id}
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 updates the specified item price markdown discount with the new configuration that you supply in the payload of the request. Specify the discount you want to update using the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's discounts.
When updating a discount, supply all the fields that you used to configure the original discount (and not just the fields you are updating). eBay replaces the specified discount with the values you supply in the update request and if you don't pass a field that currently has a value, the update request fails.
The parameters you are allowed to update with this request depend on the status of the discount you're updating:
- DRAFT or SCHEDULED discounts: You can update any of the parameters in these discounts that have not yet started to run, including the discountRules.
- RUNNING discounts: You can change the endDate and the item's inventory but you cannot change the discount or the start date.
- ENDED discounts: Nothing can be changed.
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
Parameter | Type | Description |
---|---|---|
promotion_id | string | This path parameter takes a concatenation of the ID of the discount you want to update plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an "at sign" (@). The ID of the discount (promotionId) is a unique eBay-assigned value that's generated when the discount is created. The Marketplace ID is the ENUM value of eBay marketplace where the discount is hosted. Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values. Example: 1********5@EBAY_US Occurrence: Required |
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 client credentials 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 |
---|---|---|
applyFreeShipping | boolean | If set to Occurrence: Optional |
autoSelectFutureInventory | boolean | If set to Occurrence: Optional |
blockPriceIncreaseInItemRevision | boolean | If set to Occurrence: Optional |
description | string | This field is required if you are configuring an MARKDOWN_SALE discount. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, "20% off". Maximum length: 50 Occurrence: Required |
endDate | string | The date and time the discount ends, in UTC format (
Occurrence: Required |
marketplaceId | MarketplaceIdEnum | The eBay marketplace ID of the site where the markdown discount is hosted. Markdown discounts are supported on all eBay marketplaces. Occurrence: Required |
name | string | The seller-defined name or 'title' of the discount that the seller can use to identify a discount. This label is not displayed in end-user flows. Occurrence: Required |
priority | PromotionPriorityEnum | This field is ignored in markdown discounts. Occurrence: Optional |
promotionImageUrl | string | Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, populate this field with a URL that points to an image to be used with the discount. 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 |
promotionStatus | PromotionStatusEnum | The current status of the discount. When creating a new discount, you must set this value to either Occurrence: Required |
selectedInventoryDiscounts | array of SelectedInventoryDiscount | A list that defines the sets of selected items for the markdown discount. Occurrence: Required |
selectedInventoryDiscounts.discountBenefit | DiscountBenefit | This container defines the discount as either a monetary amount or a percentage applied to the sales price. Occurrence: Required |
selectedInventoryDiscounts.discountBenefit.amountOffItem | Amount | The monetary amount that is discounted off an item (or items) when the discount criteria is met.
Occurrence: Optional |
selectedInventoryDiscounts.discountBenefit.amountOffItem.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
selectedInventoryDiscounts.discountBenefit.amountOffItem.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.discountBenefit.amountOffOrder.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
selectedInventoryDiscounts.discountBenefit.amountOffOrder.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.discountId | string | A unique, eBay-generated ID that you can use to identify the discount. This field is ignored in POST and PUT operations. Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion | InventoryCriterion | A container that defines either the listing IDs or the selection rules that specify the items to include in the discount. 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 |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.inventoryCriterion.inventoryItems.inventoryReferenceId | string | The unique identifier of a single-item listing or a multi-variation listing. Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion.inventoryItems.inventoryReferenceType | InventoryReferenceTypeEnum | Indicates the type of the inventoryReferenceId, which can be either Occurrence: Optional |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria | RuleCriteria | This container defines a set of inventory selection rules for a discount. Occurrence: Conditional |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceId | string | The unique identifier of a single-item listing or a multi-variation listing. Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceType | InventoryReferenceTypeEnum | Indicates the type of the inventoryReferenceId, which can be either Occurrence: Optional |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceId | string | The unique identifier of a single-item listing or a multi-variation listing. Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceType | InventoryReferenceTypeEnum | Indicates the type of the inventoryReferenceId, which can be either Occurrence: Optional |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules | array of SelectionRule | The container for the rules that select the items to be discounted. Occurrence: Conditional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.brands | array of string | An array of product brands. For more details, see Using the selectionRules container. Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.categoryIds | array of string | This field contains an array of the associated category ID(s). Occurrence: Conditional |
selectedInventoryDiscounts.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 |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.listingConditionIds | array of string | A comma-separated list of unique identifiers for the conditions of listings to be included Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.maxPrice | Amount | This container sets the maximum price threshold. For more details, see Using the selectionRules container. Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.maxPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.maxPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.minPrice | Amount | This container sets the minimum price threshold. For more details, see Using the selectionRules container. Occurrence: Optional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.minPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.minPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
selectedInventoryDiscounts.ruleOrder | integer | For markdown discounts, this field is reserved for future use. Occurrence: Optional |
startDate | string | The date and time the discount starts in UTC format ( Occurrence: Required |
Output
HTTP response headers
This call has no response headers.
Response payload
This call has no payload.
Response fields
This call has no field definitions.
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 |
---|---|
200 | Success |
204 | Success |
400 | Bad Request |
404 | Not Found |
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, please contact support. |
38203 | API_MARKETING | REQUEST | Resource not found. Check the ID and try the call again. |
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. |
38218 | API_MARKETING | REQUEST | A valid entry is required for {fieldName}. |
38219 | API_MARKETING | REQUEST | 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. |
38225 | API_MARKETING | REQUEST | You cannot update a promotion that has ended. |
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. |
38232 | API_MARKETING | REQUEST | You cannot update the promotion discount for an active promotion. |
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. |
38238 | API_MARKETING | REQUEST | The 'discountBenefit' data is missing, which is required by this call. 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. |
38242 | API_MARKETING | REQUEST | The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'. |
38248 | API_MARKETING | BUSINESS | The 'percentOffItem' 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. |
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}. |
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. |
38269 | API_MARKETING | REQUEST | The promotion ID does not match any of the seller's promotions. |
38270 | API_MARKETING | REQUEST | The currency type does not match what is used for the Marketplace ID submitted. |
345056 | API_MARKETING | REQUEST | The request can have only one of these field types: 'inventoryItems' or 'listingIds'. |
345057 | API_MARKETING | REQUEST | The request can have only one of these fields: 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call. |
345058 | API_MARKETING | REQUEST | When using multiple selectedInventoryDiscounts containers, each must have a unique percentageoffitems value. For help, see the documentation for this call. |
345059 | API_MARKETING | REQUEST | If using percentageoffitems you can have between 1 and 10 selectedInventoryDiscounts containers. For help, see the documentation for this call. |
345060 | API_MARKETING | REQUEST | If using amountoffitems you can only have selectedInventoryDiscounts container. For help, see the documentation for this call. |
345061 | API_MARKETING | REQUEST | The discount ID value is a read only value. |
345063 | API_MARKETING | REQUEST | Priority is not supported for the item_price_markdown calls. |
345065 | API_MARKETING | REQUEST | You cannot change the status of aa SCHEDULED promotion to DRAFT. For help, see the documentation for this call. |
345070 | API_MARKETING | REQUEST | The giving discount ID does not exist in the promotion. For help, see the documentation for this call. |
345071 | API_MARKETING | REQUEST | The giving discount type is not consistent with existing active promotion. For help, see the documentation for this call. |
345072 | API_MARKETING | REQUEST | The giving inventory criterion type is not consistent with existing active promotion. For help, see the documentation for this call. |
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. |
345120 | API_MARKETING | REQUEST | Invalid Item condition. Please refer to API documentation for allowed values. |
345121 | API_MARKETING | REQUEST | You cannot specify Rules or inventory items when using the Inventory by ALL 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. |
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. |
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 we add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label). |
345064 | API_MARKETING | REQUEST | You have moved inventory between discountBenefit containers or have the same inventory in multiple discountBenefit containers. For help, see the documentation for this call. |
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. |
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: Update a markdown discount
This sample changes the applyFreeShipping value to true
and sets the discount value to $10 (from $5) on a scheduled markdown discount. This example does not specify any inventory criterion, but to avoid a null pointer exception, it adds rule criteria with null values. The seller can specify different rule criteria with null values, or non-null rule criteria.
Input
The input to this call is a the full markdown discount as it was originally posted, plus any fields containing changed values. This sample updates both the applyFreeShipping and value fields. Use the getItemPriceMarkdownPromotion call to retrieve the details of the original and updated discount.
PUThttps://api.ebay.com/sell/marketing/v1/item_price_markdown/1*********9@EBAY_US
{"name": "Save up to $5 (All inventory example)","description": "Save up to $5 (All inventory example)","startDate": "2019-01-01T00:00:00.000Z","endDate": "2019-01-31T23:59:59.000Z","marketplaceId": "EBAY_US","promotionStatus": "SCHEDULED","promotionImageUrl": "https://i.ebayimg.com/********/********/********/s-l500.jpg","blockPriceIncreaseInItemRevision": "true","applyFreeShipping": "true","autoSelectFutureInventory": "true","selectedInventoryDiscounts": [{"inventoryCriterion": {"inventoryCriterionType": "INVENTORY_ANY","ruleCriteria": {"selectionRules": null,"excludeInventoryItems": null,"excludeListingIds": null}},"discountBenefit": {"amountOffItem": {"value": "10.00","currency": "USD"}}}]}
Output
A successful call returns the HTTP status code 204 No Content, which indicates the discount was updated as specified. This method has no response payload.