eBay Trading APIVersion 1039


This type defines the Variation container, which provides full details on each item variation in a multiple-variation listing.

Types that use VariationType:

Calls that use VariationType:


Delete ( boolean ) [0..1]
Deletes the specified variation from the listing. In general, a listing with Item Variations must have at least one variation with a non-zero Quantity in order to remain active. Additional deletion rules depend on whether you are revising or relisting.

For ReviseFixedPriceItem only: If a variation has any purchases (i.e., an order line item was created and QuantitySold is greather than 0), you can't delete the variation, but you can set its quantity to zero. If a variation has no purchases, you can delete it.

To replace a varation, you can delete it and add the new or corrected one. However, you can't specify the same SKU twice in the same request (because the intent would be ambiguous). So, either use a new SKU for the newer variation, or use the call twice (once to delete the variation, and once to add the new variation with the same SKU).

For RelistFixedPriceItem only: You can delete any variation, as long as the relisted listing includes at least 1 variation with a non-zero quantity. (That is, when you relist, you could delete all but one variation, or you could delete all existing variations and add a new one.)
See the Field Index to learn which calls use Delete.

DiscountPriceInfo ( DiscountPriceInfoType ) [0..1]
This container provides information for an item that has a Strikethrough Price (STP) or a Minimum Advertised Price (MAP) discount pricing treatment. STP and MAP apply only to fixed-price listings. STP is available on the US, eBay Motors, UK, Germany, Canada (English and French), France, Italy, and Spain sites, while MAP is available only on the US site.

Discount pricing is available to qualified sellers (and their associated developers) who participate in the Discount Pricing Program. Once qualified, sellers receive a "special account flag" (SAF) that allows them to apply Discount Pricing to both single-variation and multi-variation items. Sellers should contact their account manager or Customer Service to see if they qualify for the Strikethrough Pricing program.

As a seller listing Discount Price items, you are required to maintain records of your discount pricing in the event you are called upon to substantiate your item pricing. The following link details your legal obligations when you utilize Discount Pricing to sell items: Strikethrough Pricing Requirements

For AddFixedPriceItem, RelistFixedPriceItem, ReviseFixedPriceItem, and VerifyAddFixedPriceItem: If you are listing variations (MSKU items), use Variation.DiscountPriceInfo for each variation.
See the Field Index to learn which calls use DiscountPriceInfo.

PrivateNotes ( string ) [0..1]
A note a user makes on an item with variations in My eBay.

For eBay.com, only GetMyeBaySelling (not GetItem) returns this field, and only if you pass IncludeNotes in the request. Only visible to the user who created the note.

Not supported as input in ReviseFixedPriceItem. Use SetUserNotes instead.

In SoldList, notes for variations are only returned at the Item level, not the variation level.
See the Field Index to learn which calls use PrivateNotes.

Quantity ( int ) [0..1]
This value indicates the quantity of items in the specific variation that are available for purchase. If you set Variation.Quantity to 0 when you create, revise, or relist an item listing, the variation is dropped from the listing. To prevent this, you can set SetUserPreferences.OutOfStockControlPreference to true.

For GetItem (and other related calls that retrieve the Item object), the Variation.Quantity value indicates the total number of items associated with the variation, including the quantity available and the quantity sold. To calculate the quantity available for sale, subtract SellingStatus.QuantitySold from this value.

For RelistFixedPriceItem:
  • For an item variation that had an available quantity greater than 0 when the listing ended, the Quantity value of the item variation for the newly relisted item is set to the actual quantity available. For item variations, there is actually no QuantityAvailable field, but this value may be derived if you look at the corresponding item variation in a GetMyeBaySelling) response and subtract the Variation.QuantitySold value from the Variation.Quantity value, which represents the original Variation.Quantity value at creation time of the previous listing.
  • For item variations with an available quantity of 0 when the listing ended, the relisted item will retain the Variaton.Quantity value that was passed in at creation time of the previous listing.
So, if you are relisting an item that had one or more item variations with an available quantity of 0 when the listing ended, we strongly recommend that you pass in the correct available quantity through the corresponding Variation.Quantity field of a relist call. Alternatively, you can update the correct quantity available by using a ReviseInventoryStatus call and passing in a Quantity value, while also making sure to pass in the correct SKU value(s) to identify the correct item variation. A ReviseInventoryStatus call can be used to revise the quantity of up to four single item listings and/or item variations (from the same or different listings).

For ReviseFixedPriceItem: You can revise a variation's quantity at any time, even if it has purchases. However, unless you set the OutOfStockControlPreference boolean field of the SetUserPreferences call to true, at least one variation must remain with a non-zero quantity in order for the listing to remain active. If you set the OutOfStockControlPreference field to true, a multiple-variation listing will remain active but hidden from search even if the quantity of all variations in the listing is set to 0. When you modify a variation during revise or relist, you need to include both its StartPrice and Quantity. If you revise the Quantity value for a variation after items have already sold, specify the quantity available for sale. (eBay will automatically add the quantity sold to the value you specify.) If you set the quantity to 0 and the variation has no purchases, the variation may be dropped from the listing.

For GetSellerTransactions: See Item.Quantityinstead.

See the eBay Features Guide for more details about setting and modifying a variation's quantity.

Note: The number in the Variation.Quantity field represents the current quantity of the item variation that is available using the "Ship to home" fulfillment method. This number does not take into account any quantity of the item variation that is available through "local" fulfillment methods such as In-Store Pickup, eBay Now, or Click and Collect. This is due to the fact that there is no current implementation (or API field) where the seller informs eBay about the quantity of item variations available through each local fulfillment method. In the case where a listing is only offering the item variations through a local fulfillment method, this value should default to 0, and the Item.IgnoreQuantity will also be returned as True.
See the Field Index to learn which calls use Quantity.

SellingManagerProductInventoryStatus ( SellingManagerProductInventoryStatusType ) [0..1]
Container for statistics about the Selling Manager product that is associated with this variation.
See the Field Index to learn which calls use SellingManagerProductInventoryStatus.

SellingStatus ( SellingStatusType ) [0..1]
Contains the variation's quantity sold. Always returned when variations are present.
See the Field Index to learn which calls use SellingStatus.

SKU ( SKUType (string) ) [0..1]
A SKU (stock keeping unit) is an identifier defined by a seller. It is only intended for the seller's use (not for buyers). Many sellers assign a SKU to an item of a specific type, size, and color. For the seller's convenience, eBay preserves the SKU on the variation, and also on corresponding order line items. This enables you (as a seller) use the SKU to reconcile your eBay inventory with your own inventory system instead of using the variation specifics. It is a good idea to track how many items of each type, size, and color are selling so that you can restock your shelves or update the variation quantity on eBay according to customer demand. (eBay does not use the SKU.)

If specified, all SKU values must be unique within the Variations node. That is, no two variations within the same listing can have the same SKU.

If you set Item.InventoryTrackingMethod to true, the variation SKU values are required and they must be unique across all the seller's active listings.

For GetItem and related calls: Only returned if the seller specified a SKU for the variation.
See the Field Index to learn which calls use SKU.

StartPrice ( AmountType (double) ) [0..1]
The fixed price for this item variation. For example, a "Blue, Large" variation price could be USD 10.00, and a "Black, Medium" variation price could be USD 5.00.

Each variation requires its own price, and the prices can be different for each variation. This enables sellers to provide discounts on certain variations without affecting the price of others. Required (and always returned) for listings with variations.

You can revise a variation's price at any time (even if it has purchases). When you modify a variation during revise or relist, you need to include both its StartPrice and Quantity.
See the Field Index to learn which calls use StartPrice.

UnitCost ( AmountType (double) ) [0..1]
Cost of the Selling Manager product that matches this variation.
See the Field Index to learn which calls use UnitCost.

UnitsAvailable ( int ) [0..1]
Quantity of items in the seller's inventory for this Selling Manager product. This is not the same as the quantity available in a listed item. Required when a Selling Manager product defines variations.
See the Field Index to learn which calls use UnitsAvailable.

VariationProductListingDetails ( VariationProductListingDetailsType ) [0..1]
This container is used to provide one or more product identifiers for a product variation within a multiple-variation, fixed-price listing. If the specified product is matched to a product in the eBay catalog, some of the details on the product variation will be prefilled for the listing, including the product variation name, and item specifics for that variation of the product. The same product identifier type must be used for all product variations within the listing. For instance, if one product variation uses ISBNs, all product variations must use ISBN values.

Note: Currently, the EAN, ISBN, or UPC fields are used to specify a Global Trade Item Number (GTIN), and the GetCategoryFeatures call is used to see if particular product identifier types are supported/required. Starting later in 2017 ( dates will be announced as we approach second half of year), the NameValueList container can start being used to specify any and all GTINs, and the GetCategorySpecifics call will be the better option of retrieving the product identifier types that are supported/required. See the Required Product Identifiers Mandate (Current Phase) topic for more information on how product identifiers are currently used/specified in the Trading API, and see the Required Product Identifiers Mandate (Future Phase) topic for more information on how product identifiers will be used/specified in the Trading API beginning later in 2017. Note that the BrandMPN container, and the EAN, ISBN, and UPC fields will still be supported well into 2018.

When you specify VariationProductListingDetails, you must specify at least one GTIN. If you specify more than one of these values, eBay uses the first one that matches a product in eBay's catalog.

For ReviseItem and RelistItem only: When you revise a listing, if it ends within 12 hours, you cannot change the product identifier and you cannot remove existing product variation listing details data.
See the Field Index to learn which calls use VariationProductListingDetails.

VariationSpecifics ( NameValueListArrayType ) [0..1]
A list of name/value pairs that uniquely identify the variation within the listing. All variations must specify the same set of names, and each variation must provide a unique combination of values for those names. For example, if the items vary by color and size, then every variation must specify Color and Size as names, and no two variations can specify the same combination of color and size values.

When you revise a listing that includes variations, you can change names in variation specifics by using ModifyNameList. You can also add, delete, or replace individual variations as needed to match your current inventory. Use the Variation.Delete field to delete a variation that has no sales (order line items). If the variation has sales, then set the Quantity to 0.

For GetSellerEvents To keep the GetSellerEvents response smaller, variation specifics are not returned if the variation has a SKU. If the variation has no SKU, then variation specifics are returned instead. Optionally, you can pass IncludeVariationSpecifics as true in the request to force variation specifics to be returned, even when the SKU is returned.
See the Field Index to learn which calls use VariationSpecifics.

VariationTitle ( string ) [0..1]
The title of the variation. This is a concatenation of the listing title plus the values (no names) from the VariationSpecifics. For example, if the Title is "Polo Shirt" and the variation is for a medium pink shirt, the variation title could be "Polo Shirt[Pink,M]. PayPal may also use this value to identify item variations(for buyers and sellers).
See the Field Index to learn which calls use VariationTitle.

VariationViewItemURL ( anyURI ) [0..1]
URL for the variation on eBay. This links to eBay's View Item page, with the page configured to show details of the specified variation. The syntax of this URL is similar to Item.ViewItemURL (not optimized for natural search).
See the Field Index to learn which calls use VariationViewItemURL.

WatchCount ( long ) [0..1]
The number of watches placed on this variation by eBay users.
See the Field Index to learn which calls use WatchCount.