Revising and Relisting with Variations

This section describes rules for revising and relisting items that include variations.

Changing the Category

Adding Variations

Deleting Individual Variations

Deleting All Varations

Modifying Existing Variations

Note that if any variation within a listing has at least one purchase, the listing's item-level data is subject to the usual revision restrictions for listings with purchases.

Changing the Category

If you change the primary category of a listing with variations, the listing must adhere to all the rules (including item specifics rules) that apply to the new category. Otherwise, the listing request will fail.

When the primary category changes, you may need to specify the Variations node again. As eBay's recommendations are different for each leaf category, we suggest that you give the seller the option to review and choose from recommended variation specifics for the new category.

When you change the category, the relisted item does not retain the popularity of the original listing.

Adding Variations

To add new variations when you revise or relist, pass in the new Variation nodes. (You do not need to pass in all the original variations.) See the ReviseFixedPriceItem samples for an example.

For example, if the listing already has variations for small-size blue, medium-size black, and large-size pink colors, you could add new variations for medium-size blue and large-size black colors. As a general rule, when you add a new variation, it appears at the end of the list of variations in GetItem.

If you add new variation names or values in the new variations, be sure to also update existing variations as well as VariationSpecificsSet. See Modifying Existing Variations.

Adding a variation when relisting does not affect the sales rank or popularity of the other variations in the listing.

Deleting Individual Variations

If you want to delete a variation that has purchases, set the Quantity to 0. You cannot fully delete a variation with purchases, because the order line item data needs to remain available to the buyer(s) and the seller.

If a variation has no purchases, delete it by set the Variation.Delete field to true. (Don't use DeletedField.)

Note: DeletedField can only be used to delete a parent node or all instances of a child node (e.g., all instances of Item.PictureDetails.PictureURL). So, you can't use DeletedField to delete a single variation.

See the ReviseFixedPriceItem samples for an example.

The listing must retain at least one variation with a non-zero quantity to remain active.

Deleting a variation when relisting does not affect the sales rank or popularity of the other variations in the listing.

Deleting All Varations

To delete all variations from a listing (without replacing them with new variations at the same time):

  1. End the listing by using EndFixedPriceItem or EndItem.
  2. Create a new listing without variations by using AddFixedPriceItem or AddItem.

Modifying Existing Variations

When you modify variations, they are subject to the same rules as any new listing with variations (e.g., every variation in the relisted item must have the same set of names and a unique combination of values).

If InventoryTrackingMethod is set to SKU, you cannot modify a variation's SKU when you revise or relist.

This section covers these details:

Adding Variation Specific Names

Modifying Variation Specific Names

Modifying Variation Values

Modifying a Variation's Quantity when Revising

Modifying a Variation's Quantity When Relisting

Adding Variation Specific Names

To add new variation specifics to active listings, pass in the entire set of variation specifics in a single request, and include the new detail for all of them. For example, you could add Strap Length to a handbag listing, with varying values like Shoulder, Wrist, etc.

Modifying Variation Specific Names

When you are revising a listing, you can't delete an existing variation specific name (such as Material) from any variations, but you can change the name (e.g., to Fabric) by using ModifyNameList.

To change the name, specify the current name (e.g., Material) in ModifyNameList.Name, and the new name (e.g., Fabric) in ModifyNameList.NewName. If you are modifying the values, also be sure to specify the new name and its modified values in VariationSpecificsSet, along with the names you are not changing.

To ensure consistent results, also update Variations.Pictures.VariationSpecificName if any pictures are associated with the old name.

Note that you cannot change the name of a required item specific.

Modifying Variation Values

When you revise a listing, if you need to correct the spelling of a variation value, you first delete the variation, and then you add a new variation instead. For example, suppose you realize that a set of T-shirts that you listed with Color=Blue should use Color=Periwinkle. In this case, you would delete the variations with Color=Blue (or set their quantity to zero, if they're not eligible for deletion) and add new variations with Color=Periwinkle instead.

When you relist, you are creating a new listing, so you can change the text of the names and values. Use the same process that you use when revising listings. The relisted item is subject to the same rules as any new listing with variations (e.g., every variation in the relisted item must have the same set of names and a unique combination of values).

Modifying a Variation's Price

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.

To revise a variation's price, specify the variation to be changed in ReviseFixedPriceItem, and include the revised price in Variation.StartPrice along with the other details of the variation. You only need to specify the variation you are changing. See the ReviseFixedPriceItem samples for an example.

Alternatively, if you use SKUs to track your listings, use ReviseInventoryStatus to quickly change the prices of variations across multiple listings. Specify the variation's SKU in InventoryStatus.SKU, and the variation's price in InventoryStatus.StartPrice.

Modifying a Variation's Quantity when Revising

You can revise the quantity of a variation, even after it has purchases (order line items).

To revise a variation's price, specify the variation to be changed in ReviseFixedPriceItem, and include the revised quantity in Variation.Quantity along with the other details of the variation. You only need to specify the variation you are changing.

Alternatively, if you use SKUs to track your listings, use ReviseInventoryStatus to quickly change the quantities for variations across multiple listings. Specify the variation's SKU in InventoryStatus.SKU, and the variation's quantity in InventoryStatus.Quantity.

If you change a variation's quantity but items from it have already sold, eBay adds the quantity sold to the new quantity you specify. In other words, suppose you list with AddFixedPriceItem and set a variation's quantity to 10. A few days later, the quantity sold is 6. Now you increase your inventory and you use ReviseFixedPriceItem to set the variation's available quantity to 20. In GetItem, the variation's quantity is returned as 26 (Quantity + QuantitySold). (This means the quantity available can still be calculated as Quantity - QuantitySold.)

You can revise the quantity of any variation to zero (0), as long as at least one variation in the listing has a non-zero value. If you revise a variation's quantity to zero and the variation has never had purchases, eBay deletes the variation. If quantities of the variation have been sold, it can't be deleted (but the quantity can be zero). Also see Deleting Individual Variations for other ways to delete a variation.

If the variation sells out, and then you restock your inventory, you can revise the same variation to add more quantity, as long as the listing is still active. For example, suppose you list 50 medium blue Polo shirts in one variation and 50 medium red shirts in another. You sell all 50 medium blue shirts (so the quantity available is now zero), but the red shirts are still available. A week later, you get 20 more blue shirts in stock. You can revise the medium blue shirt variation and specify a new Variation.Quantity of 20 as long as the listing is still active.

Modifying a Variation's Quantity When Relisting

When you use RelistFixedPriceItem, each variation's quantity retains its original number (not the quantity available) unless you specifically change it.

For example, suppose your listing includes a variation with 20 blue shirts. You sell 15, leaving 5 available. Then you end and relist the listing. By default, eBay assumes the quantity of the blue shirt variation should be set to 20 (the original quantity). Therefore, it's a good idea to set the correct quantity for each variation when you relist. Use the same process that you use for revising a variation's quantity (see Modifying a Variation's Quantity when Revising).

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.