Specifying an Item's Condition

Many eBay sites support the ability to specify the condition of an item. The condition is included as part of the listing's Item Specifics.

If you want to search for existing listings based on condition, see Searching by Item Condition. Most of the details below relate to listing items (not to searching).

In the API, Item Specifics are described using the Attributes API. The Attributes API provides a standardized way to describe different aspects of a listing, such as Item Specifics (part of the item's basic description). See Working with Attribute-Based Features for general information about working with the Attributes API and definitions of terms like attribute and characteristic set.

To specify the condition of an item:

Use GetCategory2CS to retrieve the characteristic set mappings for the category in which you are listing. See Retrieving Category-to-Meta-Data Mappings.

It's a good idea to retrieve the mappings for all categories, store the results locally, and then look up the category of interest in those results.

Examine both the mapped categories and the site-wide list to determine which characteristic sets are mapped to the category in which you are listing. In particular, you need to know the characteristic set IDs (CharacteristicsSets.AttributeSetID) that are associated with each category ID.

Some sites, like eBay Germany, define a site-wide Item Condition characteristic set. This means you can use the same Item Condition attribute details for all categories that are mapped to the characteristic set.

Other sites, like eBay US, do not support a site-wide Item Condition characteristic set. This means different characteristic sets define different Item Condition attribute details. For example, some categories may support New and Used, others may support New, Used, and Refurbished, and other variations may also exist.

For US Media categories only (Books, DVD & Movies, Music, Video Games), you can use the lookup attribute fields (LookupAttribute) and specify "New" or "Used" instead of specifying the Conditon attribute (so you don't need to look up attribute IDs)..

Example 5-1 shows a snippet of a mapping in the GetCategory2CS response from the US site. (These mappings change periodically, so it is a good idea to call GetCategory2CS once a day to check for updates). This shows that category ID 98082 (a Complete Bikes & Frames category) is mapped to attribute set ID 1900 (the BMX Bikes & Frames characteristic set).

Example 5-1 A Category-to-Characteristic Set Mapping (BMX Bikes & Frames)

<Category> <CategoryID>98082</CategoryID> <CharacteristicsSets> <Name>BMX Bikes &amp; Frames</Name> <AttributeSetID>1900</AttributeSetID> <AttributeSetVersion>34709</AttributeSetVersion> </CharacteristicsSets> <ProductFinderIDs> <ProductFinderID>1848</ProductFinderID> <ProductFinderBuySide>true</ProductFinderBuySide> </ProductFinderIDs> </Category>

Use GetAttributesCS to retrieve attribute details (meta-data) for the characteristic set of interest. See Retrieving Item Specifics Meta-Data.

Table 5-1 lists the attribute details for various sites that support a site-wide Item Condition.

For sites like the US, you need to examine the GetAttributesCS response to determine the attribute definition for the characteristic set of interest (i.e., the one that is mapped to the category in which you are listing). In particular, you need the attribute and value IDs which you will use as input to AddItem (as described later in this section).

Example 5-2 shows the Condition attribute definition for a characteristic set on the US site, as returned in the GetAttributesCS response. In this case, the characteristic set ID is 1900 (BMX Bikes & Frames), the attribute ID is 10244 (Condition), and the value IDs are 10425 (New) and 10246 (Used).

Example 5-2 Item Condition Attribute Meta-Data (BMX Bikes & Frames)

<CharacteristicsSet order="2" id="1900"> <DomainName><![CDATA[BMX Bikes & Frames]]></DomainName> ... more elements here ... <Attribute labelVisible="true" id="10244"> <Label><![CDATA[Condition]]></Label> <Type><![CDATA[2]]></Type> <EditType>0</EditType> <HelpText><![CDATA[http://pages.ebay.com/help/attrhelp/contextual/ siteid0_vcsid1900_attrid10244.html]]></HelpText> <HasGlossary /> <ValueList count="3"> <Value id="-10"> <Name><![CDATA[-]]></Name> </Value> <Value id="10425"> <Name><![CDATA[New]]></Name> </Value> <Value id="10426"> <Name><![CDATA[Used]]></Name> </Value> </ValueList> <ValidationRules> </ValidationRules> </Attribute> ... more elements here ...

A number of other characteristic sets use these same IDs for the Item Condition. However, some do not. Also some characteristic sets do not define an Item Condition at all. Therefore, you should always look up the correct IDs, if any, for the category you are using.

(Optional) Retrieve the Item Specifics SYI XSL stylesheet. See Retrieving the Item Specifics SYI XSL Stylesheet.

If your application supports a graphical user interface, we usually recommend that you use the Item Specifics SYI XSL stylesheet to present Item Specifics (the attribute meta-data) to the seller.

However, if you do not want to fully support Item Specifics, and you only want to support the Item Condition, it may not be necessary to use the stylesheet.

To render the condition attribute (if any) and other Item Specifics, apply the XSL stylesheet, present the Item Specifics page to the seller, and capture the seller's selections. See Working with the Item Specifics XSL Stylesheet.

Use AddItem to add the listing with the condition the seller selected.

Use the Item.AttributeSetArray.AttributeSet property to specify the item condition attribute details when you are working with AddItem, VerifyAddItem, ReviseItem, or RelistItem requests. See Listing with Item Specifics and Catalog Data for more information about this format and the IDs you need to set.

Example 5-3 shows a snippet from an AddItem request in which the category ID is 98082 (Complete Bikes & Frames), the attribute set ID is 1900 (BMX Bikes & Frames), the attribute ID is 10244 (Item Condition), and the attribute value is 10425 (New).

Example 5-3 An Item Condition Attribute in AddItem

<PrimaryCategory> <CategoryID>98082</CategoryID> </PrimaryCategory> <AttributeSetArray> <AttributeSet attributeSetID="1900"> <Attribute attributeID="10244"> <Value> <ValueID>10425</ValueID> </Value> </Attribute> </AttributeSet> </AttributeSetArray>

Site-Wide Item Condition Details

The table below lists the site-wide characteristic set IDs, attribute IDs and value IDs that are supported on certain sites. Other sites (like the US) do not currently support site-wide attributes. You should use GetAttributesCS to programmatically determine condition attributes for individual characteristic sets (and the most recent IDs for these site-wide characteristic sets).

Table 5-1 Site-Wide Item Condition Meta-Data 

Site (ID)	AttributeSet ID	AttributeSet Label	Attribute ID	Attribute Label	Value ID	Value Label
UK (3)	1952	Item Condition	10244	Item Condition	10425	New
					10426	Used
AU (15)	2431	Item Condition	10244	Item Condition	10425	New
					10426	Used
AT (16)	2033	Artikelzustand	10244	Artikelzustand	10425	Neu
					10426	Gebraucht
DE (77)	1950	Artikelzustand	10244	Artikelzustand	10425	Neu
					10426	Gebraucht
CH (193)	2036	Artikelzustand	10244	Artikelzustand	10425	Neu
					10426	Gebraucht
IN (203)	2299	Item Condition	10244	Item Condition (required)	10425	New
					10426	Used

User-Contributed Notes