getItemPromotion

If set to true, the discount is applied only when the buyer purchases multiple quantities of a single item being discounted. Otherwise, the discount applies to multiple quantities of any items being discounted. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the discount.

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

The configuration of a coded coupon discount.

Occurrence: Conditional

A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay.

The code must be from 8-15 alphanumeric characters and can contain no more than two dashes ( - ).

This is required when the discount type is CODED_COUPON.

Occurrence: Conditional

This indicates the type of Coded Coupon discount, and is required when the discount type is CODED_COUPON.

Supported types:

• PRIVATE_SINGLE_SELLER_COUPON: Anyone can use and share the coupon code, but it isn't posted on eBay.
• PUBLIC_SINGLE_SELLER_COUPON: Anyone can find the coupon code on eBay and use it.

Occurrence: Conditional

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

Required for CODED_COUPON discounts, this is the seller-defined "tag line" for the offer, such as "Save on designer shoes." The tag line appears under the "offer-type text" that is generated for the discount and is displayed under the offer tile that is shown on the seller's All Offers page and on the event page for the discount. This tag line is not used with volume pricing discounts.

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, "Extra 20% off when you buy 3+".

Occurrence: Conditional

A list containing the discount benefits (discountRule) and the rules that define when the benefit is applied (discountSpecification).

Occurrence: Always

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:

• amountOffItem
• amountOffOrder
• percentageOffItem
• percentageOffOrder

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

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

Occurrence: Always

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

For threshold discounts, 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 discounts, 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

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

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.

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

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

The percentage applied to the sales price that is discounted off the discounted item (or items) when the discount criteria is met.

Valid integer values for percentage off:   Min: 5   Max: 80

Occurrence: Conditional

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.

Valid integer values for ORDER_DISCOUNT discounts:   Min: 5   Max: 80

For VOLUME_DISCOUNT discounts: Must be set to 0 for the first discount rule.

Occurrence: Conditional

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:

• minAmount
• minQuantity
• forEachQuantity
• forEachAmount

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 1, and in the second, set minQuantity to 2. If you include a third discountRules pair, minQuantity must be set to 3, and in a fourth, it must be set to 4. Also, you must set a ruleOrder value in each discountRules container. In the first container, discountRules must be set to 1, and in each subsequent container, the value be be incremented by 1. For more, see Configuring volume pricing discounts.

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

Occurrence: Always

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

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

Occurrence: Conditional

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

The number of items that must be purchased in order to qualify for the discount.

Valid values:
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
  12, 13, 14, 15, 16, 17, 18, 19
  20, 25, 50, 75, 100

Occurrence: Conditional

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

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

Occurrence: Conditional

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

The minimum quantity of discounted items that needs to be bought in order to qualify for the discount.

Valid values:
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
  12, 13, 14, 15, 16, 17, 18, 19
  20, 25, 50, 75, 100

Occurrence: Conditional

Use this field to configure "Buy One Get One" (or BOGO) discounts.

You must couple this field with forEachQuantity and an amountOffItem or percentOffItem field to configure your BOGO discount. This field is not valid with order-based discounts.

The value of this field represents the number of items to be discounted when other discount criteria is met. For example, when the buyer adds the number of items identified by the forEachQuantity value to their cart, they are then eligible to receive the stated discount from an additional number of like items (the number of which is identified by this field) when they add those items to their cart. To receive the discount, the buyer must purchase the number of items indicated by forEachQuantity plus the number indicated by this field.

Valid values:
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10

Occurrence: Conditional

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

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

Occurrence: Always

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

This field indicates the order in which the discountRules are presented. The value specified for this field must equal the associated minQuantity value.

Required if you are creating a volume pricing discount.

Occurrence: Conditional

The date and time the discount ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller.

Occurrence: Always

Returns either an array of listing IDs or the selection rules used to specify the items being discounted. Listing IDs can be either eBay listing IDs or an array of 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.

Occurrence: Always

Indicates how the items to be discounted are selected. You can include inventory by ID, using rules, or globally include all your inventory.

Occurrence: Always

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.

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

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

Occurrence: Conditional

An array of eBay listing IDs to be discounted.

Note: The request can have either inventoryItems or listingIds, but not both.

Occurrence: Conditional

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

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

A list of seller inventory reference IDs to exclude from the discount.

Note: The request can have either excludeInventoryItems or excludeListingIds but not both.

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

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

Occurrence: Conditional

A list of eBay listing IDs to exclude from the discount.

Note: The request can have either excludeInventoryItems or excludeListingIds but not both.

Occurrence: Conditional

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

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

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

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

Occurrence: Conditional

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

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

Occurrence: Conditional

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

The container for the rules that select the items to be discounted.

Required if inventoryCriterionType is set to INVENTORY_BY_RULE.

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

Occurrence: Conditional

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

Occurrence: Conditional

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

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

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

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

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

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:

• EBAY_AU = Australia
• EBAY_DE = Germany
• EBAY_ES = Spain
• EBAY_FR = France
• EBAY_GB = Great Britain
• EBAY_IT = Italy
• EBAY_US = United States

Occurrence: Always

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.

Maximum length: 90

Occurrence: Always

Applicable for only ORDER_DISCOUNT discounts, this field indicates the precedence of the discount, which eBay uses 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: Conditional

A unique eBay-assigned ID for the discount that's generated when the discount is created.

Occurrence: Always

Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, and not applicable for VOLUME_DISCOUNT discounts, this field is a URL that points to an image for 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

The current status of the discount. When creating a new discount, this value must be set to either DRAFT or SCHEDULED.

Occurrence: Always

Indicates the type of the discount, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT.

Occurrence: Conditional

The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller.

Occurrence: Always