eBay Trading APIVersion 1371


Variations are multiple similar (but not identical) items in a fixed-price listing. For example, a single listing could contain multiple items of the same brand and model that vary by color and size (like "Blue, Large" and "Black, Medium"). Each variation can have its own quantity and price. For example, a listing could include 10 "Blue, Large" variations and 20 "Black, Medium" variations.

Type that uses VariationsType:

Calls that use VariationsType:


ModifyNameList ( ModifyNameArrayType ) [0..1]
Modifies variation specific names when you revise or relist items.

You can modify a variation specific name regardless of the quantity sold (i.e., no restrictions on whether the item has orders or order line items (transactions)).

(Use VariationSpecifics to modify variation specific values.)

You are not required to specify SKU, VariationSpecifics, and other variation details in the request when you are only modifying a variation specific name.

Variation, Pictures, VariationSpecificsSet, or ModifyNameList (or all) need to be specified when the Variations node is specified in listing requests.
See the Field Index to learn which calls use ModifyNameList.

Pictures ( PicturesType ) [0..*]
Contains a set of pictures that correspond to one of the variation specifics, such as Color. For example, if a listing has blue and black color variations, you could choose Color for all the pictures, and then include a set of pictures for the blue variations and another set of pictures for the black variations.

We strongly recommend that you also include shared pictures in Item.PictureDetails, as this results in a better experience for buyers.

For ReviseFixedPriceItem only: To replace or delete individual pictures, pass in the entire Pictures node with the complete set of variation pictures that you want in the listing. If the applicable variations have purchases or the listing ends in less than 12 hours, you can add pictures, but you can't remove existing pictures.

Variation, Pictures, or ModifyNameList (or all) need to be specified when the Variations node is specified in listing requests

Note: Only one Pictures node is allowed for a listing. However, the node has been defined as unbounded (repeatable) in the schema to allow for different use cases for some calls or sites in the future.
See the Field Index to learn which calls use Pictures.

Variation ( VariationType ) [0..*]

Contains data that distinguishes one item variation from another. For example, if an item varies by color and size, each Variation node specifies a combination of one of those colors and sizes.

When listing or relisting an item, you are allowed to create a listing with only one item variation, and you might have a plan to add more item variations to the listing in the future. However, if you don't plan to add other item variations in the future, we recommend that you avoid listing with only one variation, so that you avoid confusing buyers.

If you specify multiple Variation containers in an add/revise/relist/verify add call to define multiple item variations, the Variation containers must be contiguous or an error will occur. This means that you would not want to input a Pictures or a VariationSpecificsSet container in between Variation containers in an API call.

When you modify an item variation with a ReviseFixedPriceItem call, the best practice is to include all applicable fields under the Variation container, even if some of the values/settings are not being modified. The StartPrice and VariationSpecifics must be included when modifying an existing item variation, even if these values are not being changed. If a SKU value is defined for the item variation, it is strongly recommended that you include the SKU field, regardless of whether the SKU value is changing or not. If the SKU field is not included, any existing SKU value will be removed from the item variation. It is also strongly recommended that you include the Quantity field and input an accurate value, because if the Quantity field is omitted in the API call, the quantity for the item variation is set to 0.
Note: The Item.Variations container and its child fields will stop being returned in GetItemTransactions on January 31, 2024.
See the Field Index to learn which calls use Variation.

VariationSpecificsSet ( NameValueListArrayType ) [0..1]
The set of all variation specific names and values that can be applicable to the listing (at any time in its life cycle). This must include all names and values specified in the VariationSpecifics nodes.

Required when Variations are specified in a new listing, and when you modify the name of a variation by using ModifyNameList. When you modify variation specific names, VariationSpecificsSet must include the new names plus the names that are not changing (but omit the old names),

This set configures variation selection widgets that appear on eBay's View Item page. For example, if you specify Color and Size names in the set, eBay's View Item page displays Color and Size drop-down lists to enable a buyer to choose a variation of interest.

The order in which you specify the names and values also controls the order in which the selection widgets appear on the View Item page. For example, if you specify "Color", then "Size", and then "Sleeve Style" as names, the View Item page shows drop-down lists with those labels in that order. For "Size", if you specify "S", "M", and "L" as values, the View Item page shows the values in that order in the Size drop-down list.

Use the getItemAspectsForCategory method of the Taxonomy API to retrieve recommendations for names and values.

Required when Variations are specified in a new listing (e.g., in AddFixedPriceItem). Also required when you change variation specific names or values in ReviseFixedPriceItem and RelistFixedPriceItem.
See the Field Index to learn which calls use VariationSpecificsSet.