promotion

The unique eBay-assigned identifier of a promotion.

Occurrence: Always

The date and time the promotion starts in UTC format (yyyy-MM-ddThh:mm:ssZ).

Occurrence: Always

The date and time the promotion ends in UTC format (yyyy-MM-ddThh:mm:ssZ).

Occurrence: Always

This enumeration value indicates the type of promotion. See the PromotionTypeEnum type description for more information on each different promotion type.

Note: Currently, only the CODED_COUPON promotion type is supported.

Occurrence: Always

The text describing the promotion.

Occurrence: Conditional

The URL for the terms and conditions page for the promotion.

Occurrence: Conditional

This enumeration value indicates the conditions of the promotion, such as 'Buy N items, and get Y off total'. See the RuleTemplateNameEnum type description for more information on what each value indicates.

This value affects discountBenefit and discountSpecification.

Occurrence: Always

A unique code that buyers can use during checkout to receive a discount.

This field is only applicable with the CODED_COUPON promotion type. It is returned as null for other promotion types.

Occurrence: Conditional

This enumeration value indicates the discount benefit of the promotion as either a monetary amount or percentage of the item/order price. See the DiscountBenefitEnum type description for more information on what each value indicates.

Occurrence: Always

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

This field will only applicable if the discountBenefit value is AMOUNT_OFF_ITEM; it is returned as null otherwise.

Occurrence: Conditional

The currency of the dollar value expressed in the amountOffItemValue field.

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

This field will only applicable if the discountBenefit value is AMOUNT_OFF_ITEM; it is returned as null otherwise.

Occurrence: Conditional

Used for threshold promotions, this is the monetary amount that is discounted off an order when the promotion criteria is met.

This field will only applicable if the discountBenefit value is AMOUNT_OFF_ORDER; it is returned as null otherwise.

Occurrence: Conditional

The currency of the dollar value expressed in the amountoffOrderValue field.

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

This field will only applicable if the discountBenefit value is AMOUNT_OFF_ORDER; it is returned as null otherwise.

Occurrence: Conditional

The percentage that is discounted off the sales price of the item (or items) when the promotion criteria is met.

This field will only applicable if the discountBenefit value is PERCENTAGE_OFF_ITEM; it is returned as null otherwise.

Occurrence: Conditional

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 will only applicable if the discountBenefit value is PERCENTAGE_OFF_ORDER; it is returned as null otherwise.

Occurrence: Conditional

This enumeration value indicates the criteria for when the discounts of a promotion trigger. The promotional discount is applied each time the specified criteria is met. See the DiscountSpecificationEnum type description for more information on what each value indicates.

Occurrence: Always

Known as the threshold amount, this is the minimum dollar amount that needs to be spent on promoted items in order to qualify for the promotional discount.

Occurrence: Conditional

The base currency applied to the value field of minAmountValue 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 that must be spent on promoted items before the promotional discount is applied, which applies for each multiple of this value on a repeating basis.

Occurrence: Conditional

The base currency applied to the value field of forEachAmountValue 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 minimum quantity of promoted items that need to be bought in order to qualify for the promotional discount.

Occurrence: Conditional

The number of items that must be purchased in order to qualify for the promotional discount, which applies for each multiple of this quantity on a repeating basis.

Occurrence: Conditional

The number of items to be discounted when other promotion criteria are met, such as forEachQuantity or minQuantity.

For example, when a buyer adds the number of items identified by these fields value to their cart, they can be eligible to receive the stated discount for an additional number of like items (specified by this field). To receive the discount, the buyer must purchase the number of items indicated by forEachQuantity or minQuantity, plus the number indicated by this field (for which they will get the discount).

Occurrence: Conditional

The maximum monetary amount a buyer can save per promotion.

Occurrence: Conditional

The base currency applied to the value field of maxDiscountAmountValue 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 maximum number of times a promotion can be redeemed per buyer.

Occurrence: Conditional

A semicolon delimited array of item IDs that are included in the promotion.

An item ID is the unique identifier of the listing in eBay RESTful format. For a single-variation listing, an example would be v1|1**********2|0. For a multiple-variation listing, an example would be v1|1**********2|4**********2, with the first set of numbers identifying the listing, and the second set of numbers identifying a specific variation within that listing.

Occurrence: Always