« 677 Trading and Shopping API Docs Now Available | Main | Developer Impact: eBay Buyer Protection in US, UK, DE »

Reminder: Old Item Condition Values Start Breaking Listings July 27

As of July 27, 2010, several categories are requiring that you specify the new, more granular Item Condition values using the new ConditionID field. This is a mandatory code change for developers.

We suggest:

Call GetCategoryFeatures for your category and site to determine if the new Item Condition values are required for that category. GetCategoryFeatures will also tell you what the possible values are.

Example request:

<?xml version="1.0" encoding="utf-8"?>
  <GetCategoryFeaturesRequest   xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
  <eBayAuthToken>ABC...123</eBayAuthToken>
  </RequesterCredentials>
  <CategoryID>63861</CategoryID>
  <Version>675</Version>
  <DetailLevel>ReturnAll</DetailLevel>
</GetCategoryFeaturesRequest> 

Example response:

...
<Category>
  <CategoryID>12345</CategoryID>
  <ConditionEnabled>Required</ConditionEnabled>
  <ConditionValues>
    <Condition>
      <ID>1000</ID>
      <DisplayName>Brand New</DisplayName>
    </Condition>
    <Condition>
      <ID>1500</ID>
      <DisplayName>New other (see details)</DisplayName>
    </Condition>
    <Condition>
      <ID>2000</ID>
      <DisplayName>Manufacturer refurbished</DisplayName>
    </Condition>
    <Condition>
      <ID>2500</ID>
      <DisplayName>Seller refurbished</DisplayName>
    </Condition>
    <Condition>
      <ID>3000</ID>
      <DisplayName>Used</DisplayName>
    </Condition>
    <Condition>
      <ID>7000</ID>
      <DisplayName>For parts or not working</DisplayName>
    </Condition>
    <ConditionHelpURL>http://pages.ebay.com/help/sell/contextual/condition_1.html</ConditionHelpURL>
  </ConditionValues>
</Category>
...

ConditionEnabled=Required means that the category requires the new way of specifying Item Condition.

Note: You will not see the value "Required" until after July 27. We suggest that you pass in ConditionID for any category that is currently flagged as "Enabled."

ID=1000 means that, to specify that the item is brand new, you should use ConditionID=1000 in your AddItem request.

DisplayName=Brand New means that you should display the value "Brand New" to your users when they are choosing their Item Condition value. You will pass the corresponding ID value in your AddItem request.

ConditionHelpURL is the help page that describes the criteria for the different conditions. For example, a "Brand New" item is described as "A brand-new, unused, unopened, undamaged item in its original packaging (where packaging is applicable). Packaging should be the same as what is found in a retail store, unless the item is handmade or was packaged by the manufacturer in non-retail packaging, such as an unprinted box or plastic bag. See the seller's listing for full details."

We recommend that you provide this URL to your user during the listing flow so they can verify that their item meets the expected criteria.

Example AddItem request:

<?xml version="1.0" encoding="utf-8"?>
  <AddItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
  <eBayAuthToken>ABC...123</eBayAuthToken>
  </RequesterCredentials>
  <ErrorLanguage>en_US</ErrorLanguage>
  <WarningLevel>High</WarningLevel>
  <Item>
   ...
  <ConditionID>1000</ConditionID>
   ...
</Item>
</AddItemRequest>

ConditionID contains the value you got from the GetCategoryFeatures ID field.

When you call GetItem, you will also see the new values returned:

Example GetItem response:

<?xml version="1.0" encoding="UTF-8"?>
  <GetItemResponse xmlns="urn:ebay:apis:eBLBaseComponents">
<Timestamp>2010-07-15T00:38:23.311Z</Timestamp>
<Ack>Success</Ack>
<Version>675</Version>
<Build>E675_CORE_BUNDLED_11481347_R1</Build>
<Item>
...
<ConditionID>1000</ConditionID>
<ConditionDisplayName>Brand New</ConditionDisplayName>
</Item>
</GetItemResponse>

After July 27:

New listings: If the new condition ID values are required, and you do not pass them in, the listing will fail.

Existing listings: If the new condition ID values are required and you try to revise the listing without passing in the new values, the revise will fail. For example, if you try to update price or quantity without also including the new item condition values, the revise will fail. The listing will continue to exist on the site, but it will not have the new price or quantity.

For more information, see:

July 14, 2010 in Best Practices, Product News, Trading API | Permalink