Configuring Variations for a Listing
To create and modify listings with variations, you use Add/Revise/Relist family of API calls. Except where specified in this documentation, listings with variations follow the same rules and support the same functionality as any other fixed-price listing.
These are the main components that you need to define for multi-variation listings:
Also note the following requirements and recommendations:
- The maximum number of variations allowed for any listing is 250.
This value is subject to change. If your application retrieves listings (using GetItem and related calls), we suggest you design it to accommodate listings that contain more than 250 variations.
- Each variation in a listing can have up to five variation details (in other words, up to five Item.Variations.Variation.VariationSpecifics nodes in the AddFixedPriceItem call), and up to 30 values for each variation details (in other words, up to 30 Item.Variations.Variation.VariationSpecifics.NameValueList.Value values under each VariationSpecifics node.
To give an example, for a multi-variation shoes listing, the variation details could include Color, Size, Width, Material, and Style, and the Color values could include Blue, White, Green, and Black.
- The recommended number of variations is 2 or more.
To support cases where the seller may have a business need to list an item and then add more variations to it later (when more inventory becomes available), the minimum requirement is 1 variation per listing. However, we recommend a minimum of 2 variations when you list with this feature. When buyers see a multi-variation listing in eBay's View Item page, they'll be offered drop-down lists from which to choose variations. eBay's research has shown that buyers are confused when only 1 variation is offered.
You can partially control the order in which variation nodes are presented:
- The order in which you specify the Variation nodes in AddFixedPriceItem or RelistFixedPriceItem is the order in which they appear in View Item, and the order in which they're returned in GetItem.
- If you subsequently add a new variation when you revise a listing, the new variation appears at the end of the list (regardless of where you specify it in ReviseFixedPriceItem).
- You can control the order of the variation-selection drop-downs that are presented in eBay's View Item page (see Configuring Variation-Selection Widgets for Buyers (View Item)).
Defining a Variation
Use VariationsEnabled in GetCategoryFeatures to determine which categories support multi-variation listings.
In the AddFixedPriceItem family of calls, use the Item.Variations.Variation node to describe each variation.
Each variation should provide enough detail to distinguish the variation from other variations in the same listing. For example, if the items vary by color and size, each variation would specify one of those colors and sizes.
For details and rules, see the following sections:
Setting Item Specifics for Variations
Using eBay Recommendations for Variation Specifics
Setting the Variation Price
Setting and Modifying a Variation's Quantity
Setting a SKU to Uniquely Identify the Variation
Setting Item Specifics for Variations
Item specifics are name/value pairs (or a name with a list of values, in some cases) that give you a structured way to describe common details about items.
- Use Item.ItemSpecifics to define item specifics that don't differ, such as Brand.
- Use Item.Variations.VariationSpecifics for details that differentiate each variation.
To help distinguish the item-level and variation-level details, this documentation (and the API) uses the term variation specifics for the variation-level item specifics. See the XML sample provided in the AddFixedPriceItem call reference for an example.
Note: This section focuses on how to specify varation specifics for individual variations. For your listing request to succeed, you also need to specify the full set of variation specifics that buyers can choose from. See Configuring Variation-Selection Widgets for Buyers (View Item).
The set of variation specifics within a variation needs to uniquely identify that variation within the listing. Therefore, the variation specifics for each variation must differ by at least one value. For example, a listing could have the following variations, where each combination of names and values is unique:
- Color=Blue, Size=M
- Color=Blue, Size=L
- Color=Black, Size=M
You can include up to five (5) name/value pairs in each variation.
For information on names that might be required in some categories, and recommendations for names that buyers are likely to search for, see Using eBay Recommendations for Variation Specifics.
If you duplicate a combination of names and values in the same listing, your listing request will fail. Therefore, your application should check for uniqueness across the variations before you submit a listing.
All variations within a listing need to specify the same set of names. For example, suppose you're listing petite and standard-sized T-shirts that have a stripe across the chest, and they're available with short or long sleeves. For each variation, you might use these five names: Size Type, Size, Color, Stripe Color, and Sleeve Style. Every variation in the listing needs to have the same number of names. That is, you can't specify one variation with five names and another variation with only three of those names.
The names in the variation specifics can't match any names in the shared item specifics. In the variation specifics, only use names that help the buyer distinguish the variations from each other.
Call GeteBayDetails to check the latest maximum characters for names and values in custom item specifics (typically 70 or less).
Each name can have up to 30 different values defined across all the variations in a listing. For example, you could have shirts in 30 different colors.
Note: As described earlier in this document, a listing can include a maximum of 250 variations. You may need to consider the maximum allowed of names and values to determine how to distribute your inventory. For example, suppose you have shirts in 20 different colors. You offer 5 sizes (S, M, L, XL, XXL). For each size, you offer 2 sleeve styles (e.g., Short Sleeved and Long Sleeved). In this case, the initial total number of variations could be 200 (20 colors x 5 sizes x 2 sleeve styles). Then you decide to also add petite sizes for each color (PS, PM, PL). Now the total number of variations could be 320 (20 colors x 8 sizes x 2 sleeve styles)--which is too many variations for one listing. To solve this, you could create separate listings for the sleeve styles. In this case, Sleeve Style would become a shared Item Specific, and the total number of variations in each listing would be 160 (20 colors x 8 sizes).
Using eBay Recommendations for Variation Specifics
Call GetCategorySpecifics to determine names that most sellers use and/or that most buyers search for. Some category-specific rules are also returned. For example:
- Most categories support free-text names and values in custom item specifics and in variations. However, some categories require certain item specifics (e.g., Brand), and some item specifics (such as Color) may require you to select a value from a predefined set.
If an item specific name is required, you can either specify it in the item-level item specifics (if it is applicable to all the variations) or within the variations (if its value changes across the variations). For example, you might specify Brand at the item level and Color within the variations.
- Some categories return a VariationSpecifics flag that identifies names (such as Color) that are recommended as variation specifics, and/or a VariationPicture flag that identifies names that are recommended for variation pictures (see Defining Pictures for Variations).
- If the recommendations say that only 1 value is allowed in item specifics, you can still specify multiple values (one per variation) in the variations. For example, if GetCategorySpecifics says that Size Type allows 1 value (MaxValues=1), you have two choices:
- Specify Size Type in the item specifics, with 1 value
- Specify Size Type in the variation specifics, with 1 value for each variation
- Like other item specifics, variation specifics can return Relationship nodes that define parent/child relationships, such as Size Type (Regular, Petite, etc.) and Size (Small, Medium, Large).
You can improve your item's chances of being surfaced in search results by specifying both the parent and the child variations in your listing when possible. For example, if you specify Size but not Size Type, and then a buyer searches against Size Type, your item might not be surfaced as a high match.
If your application has a graphical user interface, grouping parent and child fields together can help sellers understand the relationships.
Figure: Variation Relationships
Setting the Variation Price
In AddFixedPriceItem, specify the price of each variation in Variation.StartPrice.
The rules for variation prices are the same for the rules for any fixed-price listing. The price of each variation must satisfy the minimum price requirement for the site and category of the listing. The currency must match the listing site's currency. If a site or category has minimum price requirements for cross-border trade visibility, the same minimums would apply to the variation prices.
When you list with variations, do not specify Item.StartPrice. (If you do, it will be dropped with a warning.)
In GetItem and related calls, eBay sets the item-level prices (like Item.StartPrice, Item.SellingStatus.CurrentPrice, and other prices) based on the lowest-price variation that is available for purchase (with a price and quantity greater than zero). This is necessary for backward-compatibility (to support applications that are not yet variation-aware).
Note: The listing start price is recalculated within 15 minutes of an applicable event, such as a price change or when the quantity of the lowest-price variation reaches zero.
You can revise the price of a variation as long as the quantity is greater than zero (or if you increase the quantity to a non-zero value at the same time), even after it has purchases. This enables you to adjust the price competitively and to offer discounts or sales as needed.
Setting and Modifying a Variation's Quantity
Specify each variation's item quantity in Varation.Quantity. This must be a non-zero value when the variation is created.
When you list with variations, do not specify Item.Quantity. (If you do, it will be dropped with a warning.)
In GetItem, eBay shows the overall listing quantity as the sum (total) of the quantities of all the variations in the listing. This total quantity is also used to calculate any quantity-based listing fees or credits.
When items from a variation sell, the Varation.Quantity retains its original value, and Variation.SellingStatus.QuantitySold is updated (in GetItem and related calls). To determine the remaining quantity available, subtract QuantitySold from Quantity.
Listings that include variations don't support lots (Item.LotSize).
For information about changing quantities, see:
Setting a SKU to Uniquely Identify the Variation
SKUs are defined by sellers and often are used to track complex flows of products and information. When you create a fixed-price listing, you can include a SKU for your own reference. You can also specify a SKU for each variation.
If the item-level SKU is unique across all of your active eBay listings, you can use it as the listing's identifier. This means you can pass your SKU instead of the item ID in subsequent requests, such as ReviseFixedPriceItem. However, you must make this choice when you first create the listing.
When you create a listing with AddFixedPriceItem or RelistFixedPriceItem, use the InventoryTrackingMethod field to choose whether you prefer to identify the listing by item ID or by SKU. (In either case, you still have the ability to use the item ID as needed.)
You can also specify a SKU for each variation. The variation-level SKU values must be unique within the listing (and can't be the same as the Item.SKU value, if any).
When you choose to track a listing (and variations) by SKU, you can't create and track new listings by the same SKU while the existing listing is active (that is, until the existing listing with that SKU has ended). In other words, the Item.SKU value must be unique across all of your active listings that have Item.InventoryTrackingMethod set to SKU. (SKU does not need to be unique across listings that are tracked by item ID.)
When you track by item IDs, the variation-level SKU values are optional. However, if InventoryTrackingMethod is set to SKU, then the variation-level SKU values are required, and they must be unique across all the seller's active listings. (You can reuse the SKU for a new listing or variation after the listing that previously used it has ended.)
If InventoryTrackingMethod is set to SKU, you cannot modify variation-level SKU values when you revise or relist.
Note: The eBay Web site UI might not uniquely identify listings by SKU. For example, My eBay pages and Search pages all identify listings by item ID. When a buyer contacts you via eBay's messaging functionality, eBay uses the item ID as the identifier. Buyer-focused APIs (like the Shopping API) also do not support SKU as an identifier. The AddItem and RelistItem calls do not offer the inventory tracking preference. Only AddFixedPriceItem and RelistFixedPriceItem offer this preference.
Optionally, you can retrieve order line items for specific SKUs by specifying SKUArray in GetSellerTransactions.
Note: GetItemTransactions doesn't support SKU as an input because GetItemTransactions requires an identifier that is unique across your active and ended listings, such as OrderLineItemID. Even when InventoryTrackingMethod is set to SKU in a listing, eBay only requires that your SKU be unique across your active eBay listings (and not your ended listings).
Configuring Variation-Selection Widgets for Buyers (View Item)
In addition to defining each variation, you need to define the set of all possible names and values that can be applicable to the listing (at any time in its life cycle). Provide this information in the VariationSpecificsSet.
This information configures variation selection widgets that appear on eBay's View Item page. For example, if you specify Size (with options like "S" and "M") and Color (with options like "Blue" and "Pink") as names in the set, eBay's View Item page displays Size and Color drop-down lists to enable a buyer to choose a variation of interest (like medium pink).
The figure below shows a portion of the View Item page with drop-down lists that enable a buyer to choose a size and color combination.
Figure: View Item Page with Variations (Buyer View)
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 "Size", then "Color", and then "Shade" as names, the View Item page shows drop-down lists with those labels in that order. For "Size", if you specify "XS", "S", "M", "L", "XL", and "XXL" as values, the View Item page shows those values in that order in the Size drop-down list.
Note: eBay cannot reliably determine the order of the variation specifics based on the order in which you specify them in the variations themselves. This is because when you add a new variation (during a revise or relist activity) the new variation appears at the end of the list (regardless of where you specify it in your request). Over the lifetime of the listing, you may add new values, such as new colors or sizes, when you add variations. However, you can't modify the order in which names and values appear in existing variations. Thus, you need to use VariationSpecificsSet to independently define the set of all possible names and values, and the order in which to present them to buyers.
eBay analyzes the listing's latest variation data (including Quantity) against this set, and formats the View Item widgets appropriately so that buyers can only select combinations that are currently available for sale. Inapplicable combinations may be displayed as read-only or hidden (depending on eBay's ongoing analysis of factors that lead to successful sales).
Each name must have at least one (1) value. You can specify up to 30 values for each name in the set. For example, for a name like Size, you could specify XS, S, M, L, XL, XXL, and XXXL (which would be 7 values).
The information in this set is also used to crosscheck the details that you specify in the listings variations over the lifetime of the listing.
Use GetCategorySpecifics to retrieve recommendations for names, values, and order.
At a minimum, the set must include every name and value that appears in the listing's variations. In addition, it can include other values that are not yet available. For example, suppose your listing includes shirts in various sizes and colors, but all your yellow shirts are back-ordered. You can't specify yellow variations with a zero quantity when you first list the item. In this situation, you can still specify "Yellow" as one of the colors in the full set, and then revise the listing later to add the yellow variations when the items become available in your inventory.
If you add a new value in your variations, you also need to add it in VariationSpecificsSet. To do this in ReviseFixedPriceItem, pass in the entire VariationSpecificsSet node with the complete set of names and values for the listing.
Defining Pictures for Variations
A listing can have a shared (or default) set of pictures at the item level, and also pictures that help buyers visually distinguish the variations.
For the variations, you choose one variation specific name to classify (or associate with) all the variation pictures. For example, if the variations are differentiated by Color and Size, you would likely choose Color as the classifier for all the pictures. Call GetCategorySpecifics to determine which name most people usefor the variation pictures in each category.
You can specify one set of pictures for each value that matches the selected name. For example, if the name is Color, and its possible values are Blue, Black, and Pink, you can specify a set of pictures for all the blue variations, another set for all the black variations, and another set for all the pink variations.
Note: All pictures must meet the Picture Requirements.
The figure below shows one way an application can enable seller to specify a shared set of pictures and additional sets of pictures for the variations (for each color, in this case).
Figure: Multi-Variation Listing with Pictures (Seller View)
All pictures in the item-level picture set and the variation picture sets must use the same type of picture hosting (either eBay Picture Services or self-hosted pictures). You can't have a mixture of both in the same listing.
The rules and logic for pictures (including Gallery pictures) at the item-level have not changed; they are the same as for any fixed-price item (for the same site and category).
Each picture set can contain the same maximum number of pictures that are allowed at the item level (for that site and category). For example, if you can specify up to 12 eBay Picture Services pictures in the shared set (PictureDetails), then you can specify up to 12 eBay Picture Services pictures in the pink picture set, 12 in the black picture set, and 12 in the blue picture set.
Picture fees are based on the number of pictures in the set with the most pictures. So, if the shared set has 2 pictures and the pink, black, and blue sets have 3 pictures each, then fees are based on 3 pictures. If you purchase the Picture Pack option for the shared pictures (PictureDetails.PhotoDisplay=PicturePack), the option is also used for the variation pictures for no additional fee.
The shared GalleryType (in Item.PictureDetails) also applies to all the variation-level gallery pictures. The first picture in each variation picture set is used as the gallery picture for that set. The actual gallery picture displayed to users depends on how they perform the search: If a user enters a general keyword search (e.g., for "pink Polo shirt"), the gallery picture is based on the item-level picture settings. If a user uses the left-hand navigation widgets on eBay's search page and sets Color=Pink, the gallery picture is based on the first picture in the pink picture set.
Note: As the shared picture is shown in results for keyword searches, it can be helpful to use a picture that conveys information about multiple variations. For example, you could include several representative shirts in a single picture.
Pictures for variations are optional (but recommended for a better buyer experience). eBay displays all available pictures in the View Item page. The first shared (item-level) picture has initial focus in the View Item page. When a buyer chooses a variation, the focus changes to highlight the appropriate pictures. For example, if the buyer selects a blue shirt, the focus will change to the first blue picture. If you provide no pictures for the blue shirts, the shared picture will include messaging that there is no picture available for Blue.
You can revise the name associated with the pictures if the listing has no purchases and ends in more than 12 hours. If you delete the name, all the corresponding picture sets are also deleted.
If the listing has no purchases and ends in more than 12 hours, you can add more picture sets, and add or remove pictures from each set. You can also delete all the variation pictures.
If the listing has purchases or ends within 12 hours:
- You can add new picture sets
- You can add new eBay Picture Services pictures to existing picture sets
- You can't modify picture sets that contain self-hosted pictures.
Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.