Multiple-variation listings

Multiple-variation listings contain multiple items that are essentially the same product but which vary by one or more aspects, such as color and size.

For example, a particular brand and style of shirt could be available in different sizes and colors, such as "large blue" and "medium black".

Multiple-variation listings provide a structured way to differentiate between similar — but not identical — items in a multiple-quantity, fixed-price listing. For example:

• A single listing that sells women's shirts could contain multiple items of the same brand and style that vary by size and color (e.g., "Large, Blue" and "Medium, Black").
• A single listing that sells window treatments (curtains) could contain multiple items of the same brand that vary by color, length, and width.
• A single listing that sells golf clubs could contain multiple items of the same brand and model that vary by dexterity, shaft material, shaft flex, and loft.

See the following figure for an example of eBay's View Item page with a shirt variations.

eBay offers this feature in categories where sellers tend to list very similar items, such as Clothing, Shoes & Accessories. Call GetCategoryFeatures and review Category.VariationsEnabled to determine which categories support multiple-variation listings.

eBay's multiple-variation listing feature provides several benefits for sellers:

• Instead of separately listing similar items with different quantities (such as 10 small, 8 medium, and 5 large pink shirts), all the items can be consolidated into a single listing.
  • Each variation can have its own quantity, price, and an optional SKU.
  • The listing can specify shared custom item specifics (such as Brand), and each variation can also have its own variation-level item specifics (also referred to as "variation details" on the eBay marketplace) that distinguish each variation in View Item and in search results.
• There is no additional fee for listing with variations. The fee is the same as the standard fee for any fixed-price listing. In fact, as you can create one listing instead of creating multiple similar listings, you are likely to experience an overall reduction in insertion fees.
• In addition to the standard set of pictures for the listing, you can include pictures for each variation.

Selling multiple variations from the same listing is the same as selling multiple items from any other fixed-price listing.

Qualifications for listing with variations

For a listing with variations to be accepted by eBay, the seller and the listing must meet some basic qualifications.

For additional information, refer to:

• Multi-quantity listings and listings with variations (US)
• Multi-quantity listings and listings with variations (UK)
• Mehrfach-Angebote und Angebote mit Varianten (DE)

If a seller becomes ineligible to create multiple-variation listings, they cannot create new listings with variations. However, their existing listings with variations can continue (and be revised) until the next "Good 'Til Cancelled" (GTC) renewal or until ended by other means (such as items sold out or end time reached).

In the rare case that a category stops supporting multiple-variation listings, existing listings with variations can continue (and be revised) until their next GTC renewal or until ended by other means (such as items sold out or end time reached).

Define variations

To determine if a category supports multiple-variation listings, issue a GetCategoryFeatures call. If Category.VariationsEnabled returns a value of true, multiple-variations are supported.

In AddFixedPriceItem and its related calls, use Item.Variations.Variation 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.

Configure 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 do not differ for each variation (e.g., Brand).
• Use Item.Variations.Variation.VariationSpecifics for details that differentiate each variation (e.g., color, size).

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.

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 about names that might be required in some categories, as well as recommendations of names for which buyers are likely to search, refer to Use eBay recommendations as 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 are listing petite and standard-sized T-shirts that have a stripe across the chest, and they are available with short or long sleeves. For each variation, you might use these five names:

• Size Type
• Size
• Color
• Stripe Color
• Sleeve Style

The names in the variation specifics cannot 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.

Example

When deciding how to distribute inventory, it is important to consider the maximum number of names and values permitted (i.e., each listing is limited to a maximum of 250 variations). For example, a seller's shirt inventory comprises:

• 20 different colors
• 5 sizes: S, M, L, XL, XXL
• Each size is available in two sleeve styles: Short Sleeved and Long Sleeved

The total number of variations for this breakdown is 200: 20 colors x 5 sizes x 2 sleeve styles.

The seller then decides to add three petite sizes for each color: PS, PM, PL. This makes the total number of available sizes 8, and the number of variations grows to 320: 20 colors x 8 sizes x 2 sleeve styles. There are now too many variations for one listing.

One solution is to create separate listings based on the two sleeve styles. In this case, Sleeve Style would become a shared ItemSpecific field, and the total number of variations in each listing would be cut in half: 160 (20 colors x 8 sizes).

Use eBay recommendations as variation specifics

Use the getItemAspectsForCategory method of the Taxonomy API to determine which item specifics are required/recommended/available for the category in which the listing is being posted. Some category-specific rules are also returned. For example:

• Most categories support free-text names and values in item specifics and in variations. However, some categories require certain item specifics (e.g., Brand), and some item specifics (e.g., 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 which identifies names of recommended variation specifics (e.g., Color,) and/or a VariationPicture flag that identifies names that are recommended for variation pictures. Refer to Include pictures for variations for additional information.
• 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 getItemAspectsForCategory says that Size Type allows 1 value (i.e., itemToAspectCardinality = SINGLE,) there are two options:
• 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 an item's chances of being returned 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 returned as a high match.

Pricing

In AddFixedPriceItem, specify the price of each variation in Item.Variations.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 marketplace and category of the listing. The currency must match the listing marketplace's currency. If a marketplace or category has minimum price requirements for cross-border trade visibility, the same minimums would apply to the variation prices.

For GetItem and related calls, eBay sets the item-level prices (e.g., Item.StartPrice, Item.SellingStatus.CurrentPrice, and other prices,) based on the lowest-price variation that has a price, a quantity greater than zero, and is available for purchase. This is necessary for backward-compatibility (to support applications that are not yet variation-aware).

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.

Set and adjust a variation's quantity

Specify each variation's item quantity in Item.Variations.Variation.Quantity. This must be a non-zero value when the variation is created.

GetItem returns 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, Item.Variations.Varation.Quantity retains its original value, and Item.Variations.Variation.SellingStatus.QuantitySold is updated in GetItem and related calls. To determine the remaining quantity available, subtract the value for Item.Variations.Variation.SellingStatus.QuantitySold from the value for Item.Variations.Varation.Quantity.

Listings that include variations do not support lots (i.e., Item.LotSize).

For information about changing quantities, refer to:

• Modify a variation's quantity when revising
• Modify a variation's quantity when relisting

Set a SKU to identify 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, configure the InventoryTrackingMethod field to choose whether you prefer to identify the listing by itemID or by SKU. Regardless of which option is selected, you still have the ability to use the itemID as needed.

You can also specify a SKU for each variation. The variation-level SKU values must be unique within the listing and cannot be the same value as that for Item.SKU, if any.

When you choose to track a listing (and variations) by SKU, you cannot 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 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.

Optionally, you can retrieve order line items for specific SKUs by calling GetOrderTransactions and specifying the desired SKU values in ItemTransactionIDArray.ItemTransactionID.SKU.

Include 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.

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.

For additional information about including pictures in multiple-variation listings, refer to Add Pictures.

Illustrated here is 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).

Multiple-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 cannot 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 marketplace and category).

Each picture set can contain the same maximum number of pictures that are allowed at the item level (for that marketplace and category). For example, if you can specify up to 12 eBay Picture Services pictures in the shared set (i.e., Item.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.

In Item.PictureDetails, the shared GalleryType 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.

Pictures for variations are optional, but they are 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 cannot modify picture sets that contain self-hosted pictures.

Configure variations for a listing

Except where specified in this documentation, listings with variations follow the same rules and support the same functionality as any other fixed-price listing.

The main components needed to define multiple-variation listings are:

• The listing's variations, with item specifics, quantity, price, and (optionally) SKU. Refer to Define Variations.
• Instructions for validating and presenting variation-level item specifics (variation specifics) in buying tools, such as the View Item page. Refer to Configure variation-selection widgets for buyers (View Item).
• Pictures that will be associated with the variations in View Item and in search results. Refer to Include pictures for variations.

Also note the following requirements and recommendations:

• The maximum number of variations allowed for any listing is 250.

  This value is subject to change. Therefore, if your application retrieves listings by calling GetItem and related calls, we suggest you design it to accommodate listings that contain more than 250 variations in case this upper limit is increased in the future.

• Each variation in a listing can specify a maximum of five variation detail sets using the Item.Variations.Variation.VariationSpecifics.NameValueList node:

  • Each variation detail set is named using the Item.Variations.Variation.VariationSpecifics.NameValueList.Name argument.

    For example when creating a multiple-variation shoe listing these names may be:

    • Color
    • Size
    • Width
    • Material
    • Style

  • Each variation detail may then specify up to 30 unique values using the Item.Variations.Variation.VariationSpecifics.NameValueList.Value argument.

    For example, Color values could be defined as:

    • Blue
    • White
    • Green
    • Red
    • Black
    • Tan
    • Floral

• 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 (e.g., 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 multiple-variation listing in eBay's View Item page, they will be presented with 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 the Variation nodes are specified in AddFixedPriceItem and RelistFixedPriceItem calls is the order in which they appear in View Item, as well as in the response for GetItem calls.
• 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 it is specified within the ReviseFixedPriceItem call.
• You can control the order of the variation-selection drop-downs that are presented in eBay's View Item page. Refer to Configure variation-selection widgets for buyers (View Item).

Configure variation-selection widgets for buyers (View Item)

In addition to defining each variation, the set of all possible names and values that may be applicable to a listing at any point in its life cycle must also be defined. 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 (e.g., using options like "S" and "M",) and Color (e.g., using 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 following figure illustrates a portion of the View Item page with drop-down lists that enable a buyer to choose a size and color combination.

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.

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 based 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 is 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 the getItemAspectsForCategory method of the Taxonomy API to determine which item specifics are required/recommended/available.

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 cannot 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 using ReviseFixedPriceItem, pass in the entire VariationSpecificsSet node with the complete set of names and values for the listing.