--- title: "POST /item_price_markdown" method: POST path: "/item_price_markdown" tags: ["item_price_markdown"] --- # POST /item_price_markdown `POST /item_price_markdown` This method creates an item price markdown promotion (know simply as a "markdown promotion") where a discount amount is applied directly to the items included the promotion. Discounts can be specified as either a monetary amount or a percentage off the standard sales price. eBay highlights promoted items by placing teasers for the items throughout the online sales flows.

Unlike an item promotion, a markdown promotion does not require the buyer meet a "threshold" before the offer takes effect. With markdown promotions, all the buyer needs to do is purchase the item to receive the promotion benefit.

Important: There are some restrictions for which listings are available for price markdown promotions. For details, see Promotions Manager requirements and restrictions.

In addition, we recommend you list items at competitive prices before including them in your markdown promotions. For an extensive list of pricing recommendations, see the Growth tab in Seller Hub.

There are two ways to add items to markdown promotions:

New promotions must be created in either a DRAFT or a 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 (such as to schedule a promotion that's in a DRAFT state).

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

Markdown promotions are available on all eBay marketplaces. For more information, see Promotions Manager requirements and restrictions.

## Request body - ItemPriceMarkdown — This type defines the fields used to describe an item price markdown promotion. - `applyFreeShipping` boolean — If set to true, free shipping is applied to the first shipping service specified for the item. The first domestic shipping option is set to "free shipping," regardless if the shipping optionType for that service is set to FLAT_RATE, CALCULATED, or NOT_SPECIFIED (freight). This flag essentially adds free shipping as a promotional bonus.

Default: false - `autoSelectFutureInventory` boolean — If set to true, eBay will automatically add inventory items to the markdown promotion if they meet the selectedInventoryDiscounts criteria specified for the markdown promotion.

Default: false - `blockPriceIncreaseInItemRevision` boolean — If set to true, price increases (including removing the free shipping flag) are blocked and an error message is returned if a seller attempts to adjust the price of an item that's partaking in this markdown promotion. If set to false, an item is dropped from the markdown promotion if the seller adjusts the price.

Default: false - `description` string — This field is required if you are configuring an MARKDOWN_SALE promotion.

This is the seller-defined "tag line" for the offer, such as "Save on designer shoes." A tag line appears under the "offer-type text" that is generated for the promotion. The text is displayed on the offer tile that is 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. 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 - `endDate` string — The date and time the promotion ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). The value supplied for endDate must be at least 24 hours after the value supplied for the startDate of the markdown promotion.

For display purposes, convert this time into the local time of the seller.

Max value: - `marketplaceId` string — The eBay marketplace ID of the site where the markdown promotion is hosted. Markdown promotions are supported on all eBay marketplaces. For implementation help, refer to eBay API documentation - `name` string — 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 - `priority` string — This field is ignored in markdown promotions. For implementation help, refer to eBay API documentation - `promotionImageUrl` string — Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_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. - `promotionStatus` string — The current status of the promotion. When creating a new promotion, you must set this value to either DRAFT or SCHEDULED.

Note that you must set this value to SCHEDULED when you update a RUNNING promotion. For implementation help, refer to eBay API documentation - `selectedInventoryDiscounts` SelectedInventoryDiscount[] — A list that defines the sets of selected items for the markdown promotion and the discount specified for promotion. - `discountBenefit` DiscountBenefit — This container defines the promotional discount as either a monetary amount or a percentage of the sales price.

Important!: You must populate one and only one of the fields in this container:

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

- `amountOffItem` Amount — A complex type that describes the value of a monetary amount as represented by a global currency. - `currency` string — The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation - `value` string — The monetary amount in the specified currency.

Required in the amount type. - `amountOffOrder` Amount — A complex type that describes the value of a monetary amount as represented by a global currency. - `currency` string — The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation - `value` string — The monetary amount in the specified currency.

Required in the amount type. - `percentageOffItem` string — 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 - `percentageOffOrder` string — 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. - `discountId` string — A unique, eBay-generated ID that you can use to identify the discount. This field is ignored in POST and PUT operations. - `inventoryCriterion` InventoryCriterion — This type defines either the selections rules or the list of listing IDs for the promotion. The "listing IDs" are are either the seller's item IDs or the eBay listing IDs. - `inventoryCriterionType` string — Indicates how the items to include in the promotion are selected. You can include inventory by ID, using rules, or globally include all your inventory. For implementation help, refer to eBay API documentation - `inventoryItems` 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.



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. - `inventoryReferenceId` string — The seller's inventory reference ID for a listing. Also known as the "SKU" or "custom label," an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing. - `listingIds` 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. - `ruleCriteria` RuleCriteria — This type defines the fields for a set of inventory selection rules.

Required: When inventoryCriterionType is set to INVENTORY_BY_RULE or INVENTORY_ANY. - `excludeInventoryItems` 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 - `inventoryReferenceId` string — The seller's inventory reference ID for a listing. Also known as the "SKU" or "custom label," an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing. - `excludeListingIds` 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 - `markupInventoryItems` 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. - `inventoryReferenceId` string — The seller's inventory reference ID for a listing. Also known as the "SKU" or "custom label," an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing. - `markupListingIds` 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. - `selectionRules` SelectionRule[] — The container for the rules that select the items to include in a promotion.

Required if inventoryCriterionType is set to INVENTORY_BY_RULE. - `brands` string[] — An array of product brands used as an inclusion filter. A product's brand is defined in a listing's item specifics. This array will be returned if one or more product brands were used as a filter. - `categoryIds` string[] — A list of category IDs associated with the listings to be included in the campaign. Ads are created for all the seller's items listed in the specified categories, up to a maximum of 50,000 items. The IDs can be either a list of eBay category IDs (from the site where the item is hosted), or a list of category IDs defined and used by the seller's store.

eBay Marketplace category IDs
To get a list of marketplace category IDs, do one of the following:

Seller store category IDs
Because store category IDs are uniquely defined and maintained by each seller, this service cannot provide a list of a seller's IDs. However, sellers can retrieve their store category IDs as follows:

  1. Go to Seller Hub > Marketing.
  2. Click Manage store categories.
    A list of your store categories displays.
  3. Click the All categories link displayed at the bottom of the list.
    A complete list of your store categories and their associated store category IDs displays.
- `categoryScope` string — The enumeration values returned in this field indicate if the category IDs in the corresponding categoryIds array are identifiers for eBay categories or for a seller's eBay store categories. This field is always returned if one or more category IDs are used as a filter. For implementation help, refer to eBay API documentation - `listingConditionIds` string[] — A comma-separated list of unique identifiers for the conditions of listings to be included in the campaign. Up to four IDs can be specified.

This array is only returned if one or more item condition values are used as a filter.

Note: Multiple listing condition IDs are mapped to the four valid values listed below. Refer to Promoted Listings Standard campaign flow for more details.

Valid Values: - `maxPrice` Amount — A complex type that describes the value of a monetary amount as represented by a global currency. - `currency` string — The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation - `value` string — The monetary amount in the specified currency.

Required in the amount type. - `minPrice` Amount — A complex type that describes the value of a monetary amount as represented by a global currency. - `currency` string — The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation - `value` string — The monetary amount in the specified currency.

Required in the amount type. - `ruleOrder` integer — For markdown promotions, this field is reserved for future use. - `startDate` string — 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. ## Response `201` Created - object ## Other responses - `400` — Bad Request - `409` — Business Error - `500` — Internal Server Error --- [API](https://skmtc.net/ebay/apis/sell-marketing.md) · [All operations](https://skmtc.net/ebay/apis/sell-marketing/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ebay/sell-marketing/versions/de10a5d47510/schema)