Listing an Item
This section describes how to list an item.
Required Information for eBay Listings
Optional Information for eBay Listings
Required Product Identifiers Mandate (Current Phase)
Required Product Identifiers Mandate (Future Phase)
Considering Best Match When Revising and Relisting Items
Note: GetMyeBaySelling returns seller limit information for the seller if the seller is subject to seller limits. (For more information, see Seller Limits.) The returned information is the remaining quantity of items that may be listed and the remaining listing value. If these limits are exceeded, the AddItem attempt will fail. So you should invoke GetMyeBaySelling before calling AddItem or AddItems to make sure the limits will not be exceeded in the call.
See Fees Resulting from Listing an Item for more information.
- To list one item, use the AddItem call. AddItem returns the item ID (the unique identifier for the new listing), along with the fees the seller can expect to pay for the listing. See Fees Resulting from Listing an Item for more information. Because GetItem doesn't return an item's listing fees, you should save the fees returned from AddItem if you want to keep a record of the expected fees.
- To list multiple items, use the AddItems call to list up to 5 items at a time. You can also up make to 18 simultaneous AddItems calls. For more information, see Requirements for Sending Simultaneous Requests.
- To test your AddItem call, use the VerifyAddItem call. You could use VerifyAddItem to test the item's definition and give the seller a preview of the estimated listing fees, before actually listing the item. Then the application could use the same
ItemType object again, unchanged, with AddItem.
- To modify an item, use the ReviseItem or the AddToItemDescription calls.
- To relist an unsold item, use the RelistItem call. To test the RelistItem call, use the VerifyRelistItem call.
Sellers who engage in cross-border trade on sites that require a recoupment agreement must agree to the recoupment terms before using the AddItem or the VerifyAddItem. This agreement allows eBay to reimburse a buyer during a dispute and then recoup the cost from the seller.
Check for a Message node in the VerifyAddItem response because it may indicate that an AddItem attempt will be unsuccessful; see the following Knowledge Base article:
VerifyAddItem Returns Success with No Errors, but AddItem Returns Failure with Errors
See Managing Inventory for additional information about these calls.
Required Information for eBay Listings
There are a number of item properties that can be set, some required and some optional. All define how the item is displayed, how a buyer needs to go about purchasing the item, and what actions need to occur in the checkout process. See the schema documentation for
ItemType for a complete list of its properties.
This section summarizes some of the information that most eBay listings require.
Title and Description
The main descriptor is the item's title. This value is seen on the most pages and, while brief, should be composed with the intent of drawing the attention of potential buyers interested in that type of item. A title is required for item listings.
For an additional fee, you can also optionally provide a subtitle for most items, the text of which is displayed on the View Item page and is used for item searches.
Compose a description for the item that is relatively short, but that tells a user such things as what the item is, any special instructions for a buyer, and anything else that would help make the item appealing to the intended buyer.
The View Item page displays the title and description within a widget. The following are some steps you can take to make sure your content appears as expected inside a widge.
- All HTML content should have relative widths and heights.
- Images and other fixed-size objects should not exceed 700 pixels in width.
The only external links (to sites outside of eBay) allowed in listings include the following:
- Links to externally-hosted images
- Links to product videos
- Links to freight shipping services (if freight shipping is offered for item)
- Links to any legally-required information
Any external links must use the 'HTTPS' protocol (and not 'HTTP'), so if a seller's external server that is hosting images does not support the 'HTTPS' protocol, this server cannot be used. All external links should use the
For more information, see eBay's Links policy
The item's condition is required and it is recommended that you use the Item.ConditionDescription field to describe used items, as opposed to describing the condition of that item in the Item.Description field. For more information about describing the condition of an item, see Specifying an Item's Condition and the eBay help page Item conditions by category.
Site and Categories
The seller must designate the eBay site on which the item will be listed (see Standard Input Data). The seller must also specify a category on the selected site. The seller has the option to specify a second category for the same item on the same site. If a second category is selected, the item is listed simultaneously in the two categories. For more information on categories, see Categories (Introduction). For information on retrieving category details, see Retrieving the Category Hierarchy for a Site.
If you define an item and a problem occurs with the category ID you specified, see Mapping Old Category IDs to Current IDs for information about how to keep category data for individual items synchronized with eBay's category data.
If the seller is an eBay Store owner and wants to list the item in their storefront, the seller can optionally specify up to two custom categories defined for that storefront by using Storefront.StoreCategoryID and Storefront.Category2ID in addition to specifying the primary and secondary eBay categories. For additional information, see Managing Store Categories.
Free Added Category
eBay may choose at times to promote a listing with a free second category. eBay does this to help increase the visibility of the item to buyers who may be browsing in a category different than the one specified for the listing. When eBay adds a category, sellers are not charged any List in Two Categories fees for the listing. eBay may choose to add a second category to listings even on sites that normally do not support the ability to list in two categories.
The AddItem family of calls does not return any information about free added categories. However, GetItem and GetSellerList return information about the added category in a FreeAddedCategory container (and SecondaryCategory container is not returned).
If a seller submits a listing with two categories and it qualifies for a free second category, the fees returned from AddItem will reflect charges for listing in two categories, but the seller will receive a refund of any List in Two Categories fees for that listing. In this situation, GetItem and related calls return both categories in the PrimaryCategory and SecondaryCategory nodes as usual and FreeAddedCategory is not returned.
Most branded products sold on eBay must be associated with one or more recognized product identifiers. This can be a combination of brand, manufacturer part number (MPN), and Global Trade Item Number (GTIN — one of a set of globally recognized identifiers such as UPC and ISBN). These identifiers are recognized worldwide, and eBay's product catalog is keyed to them. When a seller properly identifies a product, the seller's listing for that product is automatically populated with all of eBay's catalog details about the product.
Different products have varying product identifier requirements and restrictions based on product category, brand, and field validation. You can specify product identifiers using the Item.ProductListingDetails container or the Item.ItemSpecifics container in the Add, Relist, Revise, and Verify calls. For more information about when and how to use product identifiers, see Using Product Identifiers. [[DW: provide link]]
All listings must have at least one picture of the item. You can included up to 12 pictures free of charge for all categories. For the complete list of picture requirements and information about using pictures in a listing, see Introduction to Pictures in Listings.
A new listing must have a starting price.
For an auction listing, the starting price is the price at which the progressive bidding starts. For a fixed-price listing, the starting price is the static price at which a buyer can purchase the item. Sellers can also add the Buy It Now feature to an auction listing, or assign a reserve price to the listing. If a reserve price is set, the item will not sell unless the bid of the winning bidder is higher than this price.
Price it Right
Selling using a fixed price
Standard selling fees
Note: For sites outside the US, use the site abbreviations above. For example, the following would be valid URLs:
Every listing must contain at least one payment method, and all specified payment methods should be supported by the site and by the category. For more information, see Specifying a Payment Method.
A fixed-price listing may offer one item, or a multiple quantity of items. A fixed-price listing ends when the last item has been sold (if the listing duration has not yet passed and ended the listing). An exception to this rule involves using the Out-of-Stock feature. If this feature is enabled for the seller's account, the fixed-price listing with a "Good 'Til Cancelled" listing duration will remain active (but hidden from search results) even if the quantity has gone down to
0. See the Using the Out-of-Stock Feature page for more information on this feature.
Specify the listing type to indicate if the item will sell for a static, fixed price (fixed-price listing), sell using a bidding process (auction listing), sell on Half.com (limited categories), or sell via a classified ad where the actual transaction (exchange of money between buyer and seller) takes place off of eBay platform. A listing type is required for a new item listing. If not specified in an API call, the listing type will default to an auction listing. Some listing types have other seller qualifications. For information on all listing types, see Listing Types (Formats).
A listing's duration is the time (expressed in days) that the listing will be active on the eBay site. For auction listings, the listing ends and the winning bidder is determined when this time has passed (and the highest bid matches or exceeds reserve price, if set). For fixed-price listings, the listing ends when this time has passed (though the listing could end earlier if all of the listing's items are sold or the seller ends the listing early). A fixed-price listing with a "Good 'Til Cancelled" listing duration will remain active (but hidden from search results) even if the quantity has gone down to
0 if the Out-of-Stock feature is enabled. See the Using the Out-of-Stock Feature page for more information on this feature.
We recommend you use the postal code to specify where the item is located. This enables the ability for others to search for the item based on distance from a specified zip or postal code, which improves search. For a list of valid postal code formats for countries that support search by proximity, see Search by Postal Code Proximity.
If you do not use the postal code, a seller can specify the location of the item and the country of that location. An item's location is a free-form text value, such as "San Jose, CA." The country is indicated using the ISO 3166 two-letter abbreviation for the country, such as "us" for the United States. If specify a postal code, but do not specify a location, then the location is given a default value derived from the postal code.
The country is defined using the eBay 2-letter country code set.
Use the GeteBayDetails call to see the list of currently supported codes, and the English names associated with each code (e.g., KY="Cayman Islands").
Most of the codes that eBay uses conform to the ISO 3166 standard, but some of the codes in the ISO 3166 standard are not used by eBay. Plus, there are some non-ISO codes in the eBay list. (Additional codes appear at the end of this code list and are noted as non-ISO.)
At listing time, the seller selects between using flat-rate shipping or calculated shipping. For flat-rate shipping, the seller specifies all shipping costs upfront based on the buyer's location and the shipping service selected by the buyer. In calculated shipping, eBay calculates shipping costs based on the shipping specifications (package dimensions and the weight of the item, or items if the seller is shipping multiple items to the buyer in the same shipment).
When listing in certain categories, a seller is required to provide at least one domestic shipping service. GetCategoryFeatures call can be used to find out, if a category needs shipping details provided or not. All categories with Category.ShippingTermsRequired set to
true will require at least one domestic shipping service provided.
For more on working with shipping services and costs, see Managing Shipping.
Handling (Dispatch) Time
For most items, the seller needs to specify a handling time. This indicates how long it will take for the seller to ship the item to a buyer after receiving cleared payment. This does not include the carrier's shipping time (in transit).
Top-rated sellers must offer a 0-day or 1-day handling time in order for that listing to be eligible as a Top-rated listing. The other requirement for a Top-rated listing is for the seller to accept returns for the item. Only sellers that qualify as Top-rated sellers can have Top-rated listings. For information about top-rated sellers, see http://pages.ebay.com/help/sell/top-rated.html.
The seller can also indicate where, by geographical region, the item may be shipped. This is done by specifying one shipping option, indicating: the seller will only ship to users on the same site, the seller will ship to buyers worldwide, the seller will ship to buyers on the seller's site and specified regions, or the seller will not ship the item at all. The default is to ship to buyers on the same site. If the seller indicates they will ship to the same site plus additional regions, one or more shipping regions must be specified to indicate what those additional regions are. Use GeteBayDetails with DetailName set to ShippingLocationDetails to determine which locations are valid the site. For more information, see ShipToLocation.
Sellers who provide a clear return policy are likely to sell a higher percentage of their listed items than sellers who do not have a clear return policy.
Sellers are required to specify a return policy for auction and fixed-price listings in most categories. Sellers can choose not to accept returns, but they must still specify this policy clearly. See Offering a Clear Return Policy.
Top-rated sellers must accept returns for a listing in order for that listing to be eligible as a Top-rated listing. Only sellers that qualify as Top-rated sellers can have Top-rated listings. For information about top-rated sellers, see http://pages.ebay.com/help/sell/top-rated.html.
Other Shipping Rules
Some sites, such as India, have specific shipping rules. For instance, an international listing fee applies when the seller lists items on the India site that are available for shipping outside of India.
Optional Information for eBay Listings
This section summarizes some of the additional information that can be included in a listing.
Fast Shipping and Handling
Many buyers want or need to receive an item as soon as possible after purchase (for example, last-minute shopping for the holidays). Such buyers benefit from knowing if purchasing an item from one seller would get the item into the buyer's hands faster than if purchased from another seller.
Sellers can specify prompt domestic handling and expedited shipping for items so buyers can assess whether items can be delivered within an acceptable time range.
Listings on eBay may be enhanced to make them stand out from other listings, such as on listing browse and search pages where there are multiple items from different sellers displayed on the same page. One enhancement is to show the item's title on these pages in a bold typeface. Listing enhancements are optional and all incur additional listing fees.
Sellers can use the Out-Of-Stock feature to keep their GTC (Good 'Til Canceled) items alive, even when the quantity goes down to zero. This enables them to replenish stock for the same ItemID, without the need to cancel and then relist when the item is back in stock. This feature is set once, as a seller preference, and then applied to all existing items as well as to any new item when the listing is created.
The description for an item may optionally be visually enhanced using Listing Designer templates and layouts. This makes the description as it appears on the View Item page more appealing to prospective buyers. Themes are visual accoutrements used in the item description. Themes are seasonal, based on a particular holiday, and based on personal events (like a wedding anniversary or a baby's birth). Layouts control where an item's image(s) appear in the description relative to the description's text. The seller specifies the ID for one theme and/or the ID for one layout. (Retrieving Listing Designer theme and layout IDs is not implemented in this release of the API. See GetDescriptionTemplates for more information.)
Donate a Percentage of the Sale
Specify whether or not to donate a percentage of the final sale price to a qualified nonprofit organization registered through the PayPal Giving Fund (formerly Mission Fish). These charity listings appear in the search results for the standard eBay site and in the eBay for Charity site (http://charity.ebay.com/ in the US). Charity listings will be marked with an eBay for Charity icon adjacent to the item title. A charity listing will also indicate what percentage of the sale proceeds will go towards benefiting the nonprofit organization. For more information on eBay for Charity listings, see Working with Listings that Benefit Nonprofits.
To increase the chances that your listing description will include words that buyers will search on, include Item Specifics, which are well-known features that distinguish a particular type of item according to its category. For example, in a PDA category, you could specify that the "Screen" is "Color"; whereas in a book category you could specify a "Publication Year" with a value like "1999" (and screen color would have no meaning). In most categories, the use of Item Specifics is optional. A few categories (e.g., US Real Estate) require a seller to fill in values for Item Specifics that are marked as required. Some categories do not support Item Specifics at all.
See Working with Custom Item Specifics for information about the data you need in order to include Item Specifics in a listing.
If you are new to the API, it may be easiest to first develop and test the listing functionality of your application without using Item Specifics, and then add support for Item Specifics once you have successfully created a number of listings.
Catalog Product Details
To make it even easier for buyers to find your listing, include product details from a catalog in the listing. With this option, you search an informational catalog for a stock product that is similar your item, and eBay uses that product's stock content to fill in a portion of your listing's Item Specifics and to add other information to supplement your listing description. The eBay catalog contains descriptive information only (no actual physical products). This option is available in certain categories only.
To indicate that you want to include this kind of data in your listing, you need to specify an eBay product ID (EPID) or a UPC, ISBN, EAN, or MPN. See Pre-filling Item Specifics with Product Details for more information about product details and the data you need in order to use stock information in a listing.
If you are new to the API, it may be easiest to first develop and test the listing functionality of your application without using product details, and then add the product details once you have successfully created a number of listings the standard way.
If multiple, unpaid order line items exist between the same buyer and seller, that buyer or seller have the option of combining those multiple order line items into one order. This is known as a Combined Invoice order (formerly called combined payment order). The benefits of a Combined Invoice order are:
- Only one payment is made for all order line items
- The seller is often in the position to offer the buyer discounted shipping due to the fact that it is possible to ship multiple items in one shipment
- Reduces the shipping costs for both the seller and buyer
- Less work (packing and tracking shipments) for the seller
- The buyer can possibly receive all their items at once
Shipping discount rules for flat-rate and calculated shipping are set and managed through My eBay. Optionally, shipping discount rules can be set and managed through the SetShippingDiscountProfiles API call. The shipping discounts are set in the CalculatedHandlingDiscount, CalculatedShippingDiscount, and FlatShippingDiscount containers and will apply towards eBay orders if the combined payment option is enabled.
As a seller, you control whether or not you allow buyers (or yourself) to create combined invoices. The combined payment and shipping is found in My eBay. In the API, the seller's strategy for handling combined invoice requests from buyers is set with the CombinedPaymentOption field in the SetUserPreferences call. This field takes one of the following enumeration value; if the
NoCombinedPayment value is used, the seller will not allow buyers to combine individual line items into one invoice and payment; if the
DiscountSpecified value is used, this indicates that any order discount to the buyer will be based on any calculated handling/shipping, flat-rate shipping, and/or promotional shipping rules have already been set up for the account (through My eBay or through SetShippingDiscountProfiles call); if the
SpecifyDiscountLater value is used, it will be at the seller's discretion on whether an order discount to the buyer will be offered. The maximum amount of days (the default is 30 days) in which unpaid order line items can be combined into a Combined Invoice order is set with the CombinedDuration field in SetShippingDiscountProfiles or through the Combined Payments and Shipping Discounts preferences in My eBay.
The seller may choose to have special Gift Services features used for the item's shipping to the buyer: gift wrapping and a gift card, express shipping, and shipment to the gift recipient instead of the buyer. If the GiftServices field is used in AddItem, the GiftIcon field must also be specified.
There are also a variety of other properties for an item that can be set. This includes adding a hit counter to the item's View Item page. A seller may also designate an auction or fixed-price listing as a private listing. When private listings are bid on or bought, the IDs of the bidders and the buyer are hidden for privacy reasons. A seller may also supply data that is applicable or meaningful only to the listing application. This application data is stored with the item data in the eBay database, but is never used by eBay for any purpose. It is there solely for the application's use.
Required Product Identifiers Mandate
Many eBay Categories require product identifiers, such as a UPC, an ISBN, an EAN, or a Brand/MPN pair. The next several sections discuss how to discover the eBay categories that require product identifiers, and then how to specify these product identifiers when creating or updating listings.
Note: Beginning in May 2018, some eBay categories will start requiring that all listings be associated with an eBay Catalog product. For more information, see the Product-Based Shopping Experience landing page.
Finding Categories that Support/Require Product Identifiers
The initial phase of the Product Identifier mandate rolled out in June 2015, and this mandate required that sellers provide a product identifier for new items in certain categories. However, whenever a product identifier (EAN, ISBN, UPC, Brand/MPN pair) is available for a branded product, it is always a good idea to create a listing using a product identifier, because among other benefits, it can improve search results on eBay and on other search engines, and it is a shortcut to creating a listing with robust listing information, including relative and helpful item specifics.
To see if a specific category supports or requires product identifiers, use the GetCategoryFeatures call with the following parameter options:
After a successful call, look for the EANEnabled, ISBNEnabled, and UPCEnabled fields under the Category node.
The values of each of these fields can be:
- Disabled - Indicating that particular product identifier type cannot be used in that category.
- Enabled - Indicating that the product identifier type can be used for that category.
- Required - Indicating that the product identifier type is required when listing an item in that category.
The value returned in the Category.BrandMPNIdentifierEnabled field is boolean, with
true indicating that a brand/MPN pair can be used to identify a product, and
false indicating that a brand/MPN pair cannot be used to identify a product.
Using Product Identifiers in Single-Variation Listings
Once you know that you can list your product using a product identifier, you can then set up an AddItem or AddFixedPriceItem call to create a single-variation listing.
- To identify the product using an EAN, an ISBN, or a UPC value, use the ProductListingDetails.EAN, ProductListingDetails.ISBN, or ProductListingDetails.UPC fields.
- If using a brand/MPN pair to identify the product, specify the brand/MPN pair using the ProductListingDetails.BrandMPN container and two ItemSpecifics.NameValueList containers, as shown below:
Notes on Behavior of Brand/MPN Values
The behavior of a brand/MPN pair is summarized below:
- If the seller specifies the brand/MPN pair in the ProductListingDetails and the ItemSpecifics containers, but the data in those fields are not an exact match, the data in the ItemSpecifics container will overwrite the data in the ProductListingDetails container.
- If the seller specifies the brand/MPN pair only in the ProductListingDetails container:
- If the product is found in the eBay catalog, it will be a compliant listing and the listing will be created based on that eBay catalog product.
- If the brand/MPN pair does not match a product in the eBay catalog, the listing will fail and the seller will be need to supply the brand/MPN data in the ItemSpecifics container.
- If the seller specifies the brand/MPN pair only in the ItemSpecifics container, this data will not be copied into the ProductListingDetails.BrandMPN container and resulting in the inability to do a product match in the eBay catalog.
- If specified in the ItemSpecifics container, the brand and MPN value may not exceed 65 characters.
Using Product Identifiers in Multiple-Variation Listings
The process of using product identifiers to create a multi-variation listing is slightly different. First you must use the AddFixedPriceItem call because the AddItem call doesn't support multiple variations. Also it is important to understand that the way in which you specify brand/MPN pairs and UPC, ISBN, or EAN for multi-variation listings differ. These differences are described in the next sections.
Multiple-Variation Listings Using Brand/MPN Pair
The ProductListingDetails.BrandMPN container cannot be used for multi-variation listings. If using brand and MPN (manufacturer part number) values to identify each product variation, the brand name is specified at the item level in the ItemSpecifics.NameValueList container, and the MPN for each product variation is specified at the variation level in the VariationSpecifics.NameValueList container. Examples of what the ItemSpecifics and VariationSpecifics containers would look like are shown below:
Multiple-Variation Listings Using UPC, ISBN or EAN
For multiple-variation listings, the product identifier (e.g., UPC, ISBN, or EAN) must be provided only at the variation level in the VariationProductListingDetails container. If a product identifier is provided in the Item.ProductListingDetails container for a multi-variation listing, the add/revise/relist call will fail.
An example of what the VariationProductListingDetails container would look like is shown below:
Unlike single-variation listings, using product identifiers to create a multiple-variation listing does not have the added benefit of item title, item description, product images, and item specifics being automatically picked up in the listing. So, the seller must manually add these fields along with the product identifiers.
Other Notes on Multiple-Variation Listings
- All variations within a single listing must use the same product identifier type. An error will occur if one product variation uses an EAN identifier and the rest of the product variations within the listing use a UPC identifier.
- If using brand/MPN pairs to identify each product variation, the MPN (manufacturer part number) can vary, but the Brand value cannot. If the seller tries to specify the Brand value within a VariationSpecifics container, and this Brand value conflicts with the Brand value specified at the item level in the ItemSpecifics container, the listing will fail.
- The brand and MPN value may not exceed 65 characters or the listing will fail.
For additional information, see the GTIN Mandate FAQ Knowledge base article.
Requiring Product Identifiers Mandate (Future Phase)
Note: The next phase of the Product Identifiers Mandate will be wired on later in 2017 (dates will be announced as we approach second half of 2017). This section discusses the changes coming to the Trading API calls.
Changes Coming to Product
Identifiers in eBay Listings
Benefits of Using Product Identifiers in Listings
What is Changing in the Trading API? When?
Plans to Deprecate Fields in Trading API Calls
Changes Coming to Product Identifiers in eBay Listings
The next phase of the Product Identifier mandate in eBay listings will become effective later in 2017. Here are some of main changes that sellers need to be aware of:
- New listings of new or manufacturer-refurbished
products in many categories will require at least one product identifier (e.g.
UPC, ISBN, etc.). Here is the complete list of eBay categories requiring product identifiers.
- More product identifiers will be introduced,
including Amazon Standard Identification Numbers (ASINs) and Google product identifiers
- Instead of using "Does not Apply" or "NA" in the relevant GTIN field (e.g. EAN, ISBN, or UPC), sellers will need to create their own custom IDs (e.g.
SKUs) if industry-standard identifiers are not available/applicable for
Benefits of Using
Product Identifiers in Listings
Below are the many benefits to sellers and buyers when
product identifiers are included in listings:
- Improved search visibility for these listings on
eBay Marketplace, on external search engines, and on social media sites
- Possible placement of your listings on eBay
product pages and/or browse nodes
- May get priority placement in eBay Deals, bargains, and other promotions
- Product reviews become available on your listing
- More accurate pricing guidance at listing time
- Required and recommended item specifics will
automatically be picked up in your listing if the product is found in eBay's
What is Changing in the
Trading API? When?
To account for this next phase in the Product Identifier
mandate, schema changes to several Trading API calls have been made. However, these
changes will not be made available for use in Sandbox or in Production environments until later in 2017 (dates will be announced as we get closer to second half of 2017). The specific changes to
the Trading API calls are summarized in the next several sections.
Changes to Add/Revise/Relist Item Calls
Changes to the Metadata Calls
Changes to Add/Revise/Relist Item
Instead of using the EAN, ISBN, UPC, and BrandMPN tags in the ProductListingDetails container when listing an item, these tags will be replaced by specifying the product identifier(s) through name-value pairs in the new ProductListingDetails.NameValueListcontainer. The old and new schema is demonstrated in the next several sections:
(Multiple-Variation Listing with Motor Vehicle Parts)
(Multiple-Variation Listing with Motor Vehicle Parts)
Old (Single-Variation Listing)
Note: All supporting
product identifier types are shown below for informational purposes only. There
is no use case where you would pass in all of these product identifiers.
New (Single-Variation Listing)
Note: With the new schema changes, instead of using BrandMPN, EAN, ISBN, or UPC fields, the applicable product identifier type and value will be expressed through a NameValueList container (as shown below). Another important thing to note is that a Brand value will always be specified in the ItemSpecifics.NameValueList, regardless of whether it is a single-variation or multiple-variation listing.
Old (Multiple-Variation Listing)
New (Multiple-Variation Listing)
Note: With the new schema changes, instead of using EAN, ISBN, or UPC fields under the VariationProductListingDetails container for each product variation, the applicable product identifier type and value will be expressed through a NameValueList container (as shown below). Another important thing to note is that a Brand value will always be specified in the ItemSpecifics.NameValueList, regardless of whether it is a single-variation or multiple-variation listing.
Old (Multiple-Variation Listing with Motor Vehicle Parts)
New (Multiple-Variation Listing with Motor Vehicle Parts)
Note: With the new schema changes, instead of using a MPN field under the VariationProductListingDetails container for each part/accessory variation, the applicable product identifier type (always
MPN in this use case) and its value will be expressed through a NameValueList container (as shown below). Just like before, the brand will be specified through a ItemSpefics.NameValueList container at the listing level.
Note: If creating a single-variation, motor vehicle part listing with the new schema, the Brand value will still be specified in the ItemSpecifics.NameValueList container, and the MPN value will be passed in through a Variation.VariationProductListingDetails.NameValueList container.
Changes to the Metadata Calls
Currently, sellers have to use the GetCategoryFeatures call to see
if a category supports or requires EAN, ISBN, or UPC product
identifiers. And, if a category requires a particular product identifier, but
the seller does not have this value, that seller must make a GeteBayDetails
call to get the text string that must be passed into the appropriate product
identifier field under the ProductListingDetails or VariationProductListingDetails containers in an Add listing call. Finally, that seller would have to make a GetCategorySpecifics call to get recommended item specifics for the category.
With the upcoming changes to the APIs, only the GetCategorySpecifics
call will be needed to see which product identifiers are supported or required
for a category, as well as the recommended item specifics for the category. A
snippet for the GetCategorySpecifics
call is shown below, with existing fields appearing in black, and new fields
appearing in blue.
The product identifier types that are supported for the category are returned under the ProductIdentifiers container. The ValidationRules.MinRequired value that is returned will indicate how many of the product identifiers are required. It could be that the seller has an option of specifying two different product identifier types, but only one is required. If this is the case, the ValidationRules.MinRequired value would be
1. For categories that do not support or do not require product identifiers, the ValidationRules.MinRequired value would be
0. The following product identifiers will be supported:
- ASIN (Amazon Standard Identification Number)
- Brand (generally used with MPN)
- Custom ID (seller-defined, like a SKU)
- EAN (European Article Number)
- Google product identifier
- ISBN (International Standard Book Number)
- MPN (Manufacturer Part Number; generally used with Brand)
- UPC (Universal Product Code)
Plans to Deprecate Fields in Trading
As the new schema gets wired on in the Trading API calls, there are plans to deprecate the fields that will be replaced by the new schema. The old schema will eventually be deprecated. Exact timing of deprecation will be announced later in 2017, but the old schema will still be supported well into 2018. The following sections will cover which fields will be deprecated.
ProductListingDetails Type Used in Listing Calls
GetCategoryFeatures Planned Deprecations
GeteBayMetadata Planned Deprecations
ProductListingDetails Type Used in Listing Calls
The ProductListingDetails type is used in Add/Revise/Relist
calls to identify a product through a product identifier. If the product
identifier is matched to a product in the eBay catalog, the eBay listing is
partially pre-filled with item title, description, item specifics, etc. The
following fields in this type will be deprecated:
Instead of using
these fields in ProductListingDetailsType, the seller will use the newly introduced NameValueList container to
specify the product identifier as a name-value pair, as demonstrated below:
Note: In addition to the Add/Revise/Relist calls, the ProductListingDetails type is also used by GetItem. For a full list of Trading API calls that use the ProductListingDetails type, see the type definition here
GetCategoryFeatures Planned Deprecations
Among many other things, the GetCategoryFeatures call is used to see which product identifier types are supported/required by a specific category. By passing in
UPCEnabled values in a FeatureID field in the request payload, the seller is notified through the call response if those specific product identifier types are supported/required by a specific category.
The corresponding fields that are returned in the response at the site level, feature level, and category level are BrandMPNIdentifierEnabled, EANEnabled, ISBNEnabled, and UPCEnabled. These fields will eventually be deprecated and no longer returned. To account for these deprecations, these fields will be removed from CategoryFeatureType and SiteDefaultsType. Additionally, the following types will be completely deprecated: BrandMPNIdentifierEnabledDefinitionType, EANEnabledDefinitionType, ISBNEnabledDefinitionType, and UPCEnabledDefinitionType.
Instead of using GetCategoryFeatures to see which product identifiers are supported for a category, the seller will use GetCategorySpecifics and look at the ProductIdentifiers container that is returned for the category.
Among many other things, the GeteBayMetadata call is used to retrieve the text string that should be passed into a product identifier field (e.g. EAN, ISBN, UPC) in an AddItem call when the seller's item does not have a product ID. To retrieve this text string in the GeteBayMetadata call, the seller passes in the
ProductDetails enumeration value in a DetailName field, and then looks for the ProductDetails.ProductIdentifierUnavailableText field in the response. The value in this field is then passed into a product identifier field (e.g. EAN, ISBN, UPC) in an AddItem call. Both the
ProductDetails enumeration value in DetailNameCodeType and the ProductDetailsType (used by GeteBayMetadata) will be deprecated.
Instead, in a case
where a standard product identifier type is not available, the seller will use
a CustomID name and value (as long as that category
supports CustomID values) in the ProductListingDetails.NameValueListcontainer of an AddItem call. To make sure a category supports CustomID values, the seller will call GetCategorySpecifics and look for CustomID under the ProductIdentifiers
container in the response. If a CustomID is
supported, then the seller will use the new NameValueList
container to specify the custom ID value as a name-value pair, like below:
Other Important Things to Know
few sections will cover some additional information that is important to know
as eBay transitions to the new procedure of specifying/using identifiers.
Notes on Timing
No Mixing and Matching Old and New Schema
Revising Existing Listings with New Schema
Notes on Timing
The new schema related to the next phase in the Product Identifier mandate has already been introduced in listing calls and in the GetCategorySpecifics call, but this schema will not be available for use until later in 2017.
Once the new schema becomes available in the Production environment, the old schema may be wired off for that train and later trains going forward, so users will have to use older versions of the Trading WSDL to use the old schema related to product identifiers. The exact version numbers will be shared as we get closer to the second half of 2017 and the new schema is wired on.
No Mixing and Matching Old and New Schema
Whether it is in the Sandbox or Production environment, users may not mix and match old and new schema elements. For example, the user would not be able to specify a UPC value using the UPC field (old schema) and then specify an ISBN value using a NameValueList container (new schema) in the same ProductListingDetails container.
Revising Existing Listings with New
Existing listings, created using old schema, can be revised
with the new schema through a ReviseItemor ReviseFixedPriceItem call. The user will just use the NameValueList container in ProductListingDetails to specify a product identifier type and value instead of using the EAN, ISBN, or UPC fields.
More information on product identifiers and structured data can be found in the Fall 2016 Seller Release. To get a complete list of categories that support/required product identifiers, see the Structured Data - Product Identifiers help page. This page specifies which categories were already enabled with product identifiers through the previous product identifier mandate, as well as those categories that are newly enabled with this next phase of the product identifier mandate.
As part of the first phase of the Product Identifiers mandate (rolled out in late June 2015), sellers on the US, UK, Germany, and Australia sites were required to provide product identifiers at listing time for new products in certain categories.
Considering Best Match When Revising and Relisting Items
When users search for items on eBay, the default way items are sorted is Best Match.
When you list an item, you can consider how to improve its placement, or rank, in search results. When you revise or relist an item, consider the item's performance score (i.e., the ratio of sales to impressions). An item's performance score affects the item's rank in search results.
Revising an item doesn't affect its performance score, in most cases. Similarly, relisting an item will carry over an item's performance score, regardless of changes made, in most cases. However, whether you are revising or relisting, either of the following changes will reset an item's performance score:
- Category updates (changing, adding, or removing) for either the primary or secondary category will trigger a reset
- Item condition removal
Note: When relisting an item, the item performance score carries over for the first new item only. That is, if an item is relisted multiple times, only the first new item inherits the performance score. When it is time to relist the new item, its performance score carries over for the first new item only, as well.
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.