【eBay API落とし穴】Action FigureカテゴリでUSEDが登録できない理由と対策

背景

Action Figureカテゴリでは、eBayの出品画面（UI）上、コンディションは NEW と USED の2択しか表示されません。

しかし、Inventory API で SKU を作成する際、USED をそのまま指定するとエラーが発生します。

原因

eBayのAPI仕様では、"USED" という ConditionEnum が存在しない ためです。

UI表記 → 「USED」
API実体 → USED_EXCELLENT (Condition ID: 3000)

つまり、UIの「USED」をAPIで再現するには、USED_EXCELLENT を使う必要があります。

参考資料

• createOrReplaceInventoryItem - Inventory API
  • https://developer.ebay.com/api-docs/sell/inventory/resources/inventory_item/methods/createOrReplaceInventoryItem#request.availability
• ConditionEnum 定義
  • https://developer.ebay.com/api-docs/sell/inventory/types/slr:ConditionEnum

解決例

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
      }
    }
  }'

エラー内容：

{
  "errors": [
    {
      "message": "Could not serialize field [condition]"
    }
  ]
}

成功例

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", # 中古にしたい場合は、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
      }
    }
  }'

これで無事、Action Figure の USED 出品が可能に。

まとめ

• Action Figure のように、UI（画面）上では「New」と「Used」しか選択できないカテゴリでも、eBay Inventory API では condition に「USED」という文字列は存在しない。
• 代わりに、USED_EXCELLENT が Used の代替として利用される。（Condition ID は 3000）
• つまり、こうしたカテゴリでは：
  • 新品なら → "condition": "NEW"
  • 中古なら → "condition": "USED_EXCELLENT"
• これは API の仕様と eBay の ConditionEnum の設計上の理由によるものだが、ドキュメントや UI に明記されておらず非常に分かりづらいポイント。