Skip to main content

GET/item_price_markdown/{promotion_id}

This method returns the complete details of the item price markdown promotion that's indicated by the promotion_id path parameter.

Call getPromotions to retrieve the IDs of a seller's promotions.

Input

Resource URI (production)

GET https://api.ebay.com/sell/marketing/v1/item_price_markdown/{promotion_id}

URI parameters

ParameterTypeDescription
promotion_idstringThis path parameter takes a concatenation of the ID of the promotion you want to get plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

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.

This method has no additional required headers. See HTTP request headers- opens rest request components page for details.

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

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* ItemPriceMarkdown */
"name" : "string",
"selectedInventoryDiscounts" : [
{ /* SelectedInventoryDiscount */ }
],
}

Response fields

Output container/fieldTypeDescription
applyFreeShippingboolean

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

Occurrence: Conditional

autoSelectFutureInventoryboolean

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

Occurrence: Conditional

blockPriceIncreaseInItemRevisionboolean

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

Occurrence: Conditional

descriptionstring

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

Occurrence: Conditional

endDatestring

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:

  • 14 days for the AT, CH, DE, ES, FR, IE, IT, and UK, marketplaces.
  • 45 days for all other marketplaces.

Occurrence: Conditional

marketplaceIdMarketplaceIdEnum

The eBay marketplace ID of the site where the markdown promotion is hosted. Markdown promotions are supported on all eBay marketplaces.

Occurrence: Always

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: Conditional

priorityPromotionPriorityEnum

This field is ignored in markdown promotions.

Occurrence: Conditional

promotionImageUrlstring

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.

Occurrence: Conditional

promotionStatusPromotionStatusEnum

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.

Occurrence: Always

selectedInventoryDiscountsarray of SelectedInventoryDiscount

A list that defines the sets of selected items for the markdown promotion and the discount specified for promotion.

Occurrence: Conditional

selectedInventoryDiscounts.discountBenefitDiscountBenefit

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

Occurrence: Always

selectedInventoryDiscounts.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: Conditional

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

selectedInventoryDiscounts.discountBenefit.amountOffItem.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

selectedInventoryDiscounts.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: Conditional

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

selectedInventoryDiscounts.discountBenefit.amountOffOrder.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

selectedInventoryDiscounts.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: Conditional

selectedInventoryDiscounts.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: Conditional

selectedInventoryDiscounts.discountIdstring

A unique, eBay-generated ID that you can use to identify the discount. This field is ignored in POST and PUT operations.

Occurrence: Conditional

selectedInventoryDiscounts.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: Always

selectedInventoryDiscounts.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: Always

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



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

selectedInventoryDiscounts.inventoryCriterion.inventoryItems.inventoryReferenceIdstring

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.

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.inventoryItems.inventoryReferenceTypeInventoryReferenceTypeEnum

Indicates the type of the inventoryReferenceId, which can be either an individual item or a multi-SKU item (INVENTORY_ITEM and INVENTORY_ITEM_GROUP, respectively).

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

Occurrence: Conditional

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

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

selectedInventoryDiscounts.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: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceIdstring

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.

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.excludeInventoryItems.inventoryReferenceTypeInventoryReferenceTypeEnum

Indicates the type of the inventoryReferenceId, which can be either an individual item or a multi-SKU item (INVENTORY_ITEM and INVENTORY_ITEM_GROUP, respectively).

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

Occurrence: Conditional

selectedInventoryDiscounts.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: Conditional

selectedInventoryDiscounts.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: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceIdstring

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.

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.markupInventoryItems.inventoryReferenceTypeInventoryReferenceTypeEnum

Indicates the type of the inventoryReferenceId, which can be either an individual item or a multi-SKU item (INVENTORY_ITEM and INVENTORY_ITEM_GROUP, respectively).

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

Occurrence: Conditional

selectedInventoryDiscounts.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: Conditional

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

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.brandsarray of string

The list of brands in the seller's inventory to include in the promotion.

This field is applicable only when categoryScope is set to MARKETPLACE.

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.categoryIdsarray of string

Each selectionRules container can specify only a single category ID to include in the promotion. The ID can be either an eBay category ID or a seller's store category ID.

Marketplace (eBay) category IDs
While we do not publish a list of eBay category IDs, you can retrieve the list of IDs as follows:

  • Get the category ID from the marketplace site:
    1. Use the Taxonomy API to retrieve a list of category IDs for any marketplace.
    2. For any marketplace, add /sch/allcategories/all-categories to the URL of the marketplace and navigate to that page.
      For example: http://www.ebay.com.au/sch/allcategories/all-categories
    3. Navigate to the category that you want and copy the ID from the URL.
  • For the US: See Category Changes for the latest list of category IDs.
Store category IDs
Store category IDs are unique to each seller, so the service cannot provide a list of them. To retrieve a list of seller Store category IDs:
  1. Go to Seller Hub > Marketing.
  2. Click Manage store categories.
    You will see a list of your store categories.
  3. At the bottom of the list, click All Categories.
    A complete list of your Store categories and their associated Store category IDs displays.
Note: You must always specify both categoryIds and categoryScope fields in each selectionRules container. If you specify multiple selectionRules containers, the categoryScope in each must match (they must all be either MARKETPLACE or STORE).

Required if inventoryCriterionType is set to INVENTORY_BY_RULE.

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.categoryScopeCategoryScopeEnum

The type of the category ID for the item(s) to be included in the promotion. You must always supply both categoryIds and categoryScope. Note: A request can have only one categoryScope.

Required: When inventoryCriterionType is set to INVENTORY_BY_RULE.

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.listingConditionIdsarray of string

A list of IDs that describe the condition of the items included in the promotion. For more information, see Item condition ID and name values.

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

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.maxPriceAmount

This sets the maximum value of the price range for the items included in the promotion. Only items whose price is equal to or less than maxPrice are included in the promotion.

Important: You must set minPrice if you set maxPrice.

Occurrence: Conditional

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

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.maxPrice.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.minPriceAmount

This sets the minimum value of the price range for the items included in the promotion. Only items whose price is equal to or greater than minPrice are included in the promotion.

Important: You must set maxPrice if you set minPrice.

Occurrence: Conditional

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

selectedInventoryDiscounts.inventoryCriterion.ruleCriteria.selectionRules.minPrice.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

selectedInventoryDiscounts.ruleOrderinteger

For markdown promotions, this field is reserved for future use.

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: 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
200Success
400Bad Request
404Not Found
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.
38203API_MARKETINGREQUESTResource not found. Check the ID and try the call again.
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.

Warnings

This call has no warnings.

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: Gets a specific markdown promotion

This sample returns the details for the specified markdown promotion.

Input

Specify the markdown promotion you want to retrieve using the promotion ID concatenated with the marketplace ENUM as a URI query parameter. See the endpoint below for an example.

GEThttps://api.ebay.com/sell/marketing/v1/item_price_markdown/1********9@EBAY_US

Output

The output is the complete details of the markdown promotion.