Why “USED” Condition Fails in eBay Inventory API (Action Figure Category)

This content originally appeared on DEV Community and was authored by Snowball

Background

In the Action Figure category on eBay, the listing UI only provides two condition options:

NEW and USED.

However, when creating a SKU using the eBay Inventory API, specifying "USED" directly causes an error.

Root Cause

According to eBay’s API specification, the enum value "USED" does not exist.

UI Label → "USED"
API Expected Value → "USED_EXCELLENT" (Condition ID: 3000)

So, to reproduce the UI’s “USED” condition in the API, you need to use "USED_EXCELLENT" instead.

References

Example: Fails with `"USED"`

curl -X PUT 'https://api.ebay.com/sell/inventory/v1/inventory_item/test-sku-001' \
  -H "Authorization: Bearer DUMMY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "condition": "USED",
    "product": {
      "title": "Dummy Action Figure",
      "description": "Dummy description for an action figure item.",
      "imageUrls": ["https://dummyurl.com/dummy-image.jpg"]
    },
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 1
      }
    }
  }'
\```
{% endraw %}


### Error Response

\
{% raw %}
```json
{
  "errors": [
    {
      "message": "Could not serialize field [condition]"
    }
  ]
}
\```
{% endraw %}


## ✅ Example: Success with {% raw %}`"USED_EXCELLENT"`

\
{% raw %}
```bash
curl -X PUT 'https://api.ebay.com/sell/inventory/v1/inventory_item/test-sku-001' \
  -H "Authorization: Bearer DUMMY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "condition": "USED_EXCELLENT",
    "product": {
      "title": "Dummy Action Figure",
      "description": "Dummy description for an action figure item.",
      "imageUrls": ["https://dummyurl.com/dummy-image.jpg"]
    },
    "availability": {
      "shipToLocationAvailability": {
        "quantity": 1
      }
    }
  }'
\```
{% endraw %}


Now the **USED** listing works correctly via API.

## Summary

- In the Action Figure category (and similar), the **UI only shows "New" and "Used"**, but...
- The eBay Inventory API **does not accept {% raw %}`"USED"`{% endraw %}**.
- Instead, use {% raw %}`"USED_EXCELLENT"`{% endraw %} (Condition ID {% raw %}`3000`{% endraw %}) when listing as used.
- Therefore:
  - New item → {% raw %}`"condition": "NEW"`{% endraw %}
  - Used item → {% raw %}`"condition": "USED_EXCELLENT"`{% endraw %}
- This mismatch stems from eBay’s internal {% raw %}`ConditionEnum`{% endraw %} design and is **not clearly documented**, making it a common source of confusion for developers.

This content originally appeared on DEV Community and was authored by Snowball

Background

Root Cause

References

Example: Fails with "USED"

Example: Fails with `"USED"`