通过REST API推送至亚马逊时商品标题、库存、图片缺失问题

问题背景 #

使用Amazon SP-API创建APPAREL类商品Listing，API返回ACCEPTED但亚马逊后台显示标题、库存、图片缺失，状态为Incomplete。提交的Payload和响应如下：

提交的Payload #

{
  "productType": "APPAREL",
  "requirements": "LISTING",
  "attributes": {
    "brand": [
      {
        "value": "GENERIC",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "bullet_point": [
      {
        "value": "it's an awesome luggage",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "country_of_origin": [
      {
        "value": "US",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "item_name": [
      {
        "value": "Awesome Luggage",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "product_description": [
      {
        "value": "This is a test description",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "supplier_declared_dg_hz_regulation": [
      {
        "value": "not_applicable",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "recommended_browse_nodes": [
      {
        "value": "12587455",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "merchant_suggested_asin": [
      {
        "value": "B007KQBXN0",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "item_package_dimensions": [
      {
        "height": {
          "value": 2.7,
          "unit": "inches"
        },
        "length": {
          "value": 10,
          "unit": "inches"
        },
        "width": {
          "value": 2,
          "unit": "inches"
        },
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "batteries_required": [
      {
        "value": true,
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "color": [
      {
        "value": "Cranberry",
        "standardized_values": ["Red"],
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "externally_assigned_product_identifier": [
      {
        "title": "Item Package Dimensions",
        "description": "Provide the item's package dimensions"
      }
    ],
    "manufacturer": [
      {
        "value": "Everyday Manufacturing Company",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "unit_count": [
      {
        "value": 72.0,
        "type": {
          "value": "Ounces",
          "language_tag": "en_US"
        },
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "item_package_weight": [
      {
        "value": 0.65,
        "unit": "pounds",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "batteries_included": [
      {
        "value": true,
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "battery": [
      {
        "cell_composition": [
          {
            "value": "alkaline"
          }
        ]
      }
    ],
    "list_price": [
      {
        "currency": "SAR",
        "value_with_tax": 69,
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "target_gender": [
      {
        "value": "female",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "department": [
      {
        "value": "Unisex Baby",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "outer": [
      {
        "material": [
          {
            "value": "Leather",
            "language_tag": "en_US"
          },
          {
            "value": "Carbon Fiber",
            "language_tag": "en_US"
          }
        ],
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "age_range_description": [
      {
        "value": "Toddler",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "weave_type": [
      {
        "value": "Jacquard",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "model_name": [
      {
        "value": "MacBook Pro",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "care_instructions": [
      {
        "value": "Hand Wash Only",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "fabric_type": [
      {
        "value": "75% Cotton, 15% Nylon, 10% Rayon",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "size": [
      {
        "value": "X-Large",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "closure": [
      {
        "type": [
          {
            "value": "Zipper",
            "language_tag": "en_US"
          }
        ],
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "style": [
      {
        "value": "Art Deco",
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ],
    "main_product_image_locator": [
      {
        "marketplace_id": "A17E79C6D8DWNP",
        "media_location": "https://d1gpzof0viq1mp.cloudfront.net/products/thumb/073120200027085f23655c3b789.png"
      }
    ],
    "item_name": [
      {
        "language_tag": "en_US",
        "marketplace_id": "A17E79C6D8DWNP",
        "value": "Adidas Blue Sneakers"
      }
    ],
    "list_price": [
      {
        "currency": "SAR",
        "value_with_tax": 1.00,
        "marketplace_id": "A17E79C6D8DWNP"
      }
    ]
  }
}

API返回响应 #

{
  "sku": "3333-4567-8910",
  "status": "ACCEPTED",
  "submissionId": "bf09b1753c174a1cbba81b63568560e1",
  "issues": []
}

疑问解答 #

1. 标题、库存、图片缺失的可能原因 #

• 标题问题：Payload中重复定义了item_name字段，JSON规范不允许对象存在重复键，解析时通常会保留最后一个值，但亚马逊SP-API可能对这种非法格式处理异常，导致标题未被正确存储。
• 库存问题：Listings API仅负责商品基础信息的创建，库存数量需要通过Inventory API单独设置，你提交的Payload中未包含任何库存相关字段，亚马逊后台自然显示库存缺失。
• 图片问题：
  • 检查main_product_image_locator中的media_location是否为亚马逊可公开访问的URL（需确保无防盗链、权限限制）；
  • 图片格式、分辨率需符合亚马逊要求（比如JPG格式，最小1000x1000像素）；
  • 确认该字段是否为APPAREL类商品的正确图片字段，部分品类可能需要使用其他字段。

2. 亚马逊认定商品完整的必填字段 #

亚马逊对不同商品类型的必填字段不同，可通过以下方式获取：

• 调用Product Type Definition API时，指定requirements=REQUIRED，返回的schema中标记为mandatory的字段即为必填项；
• 对于APPAREL类商品，核心必填字段至少包括：
  • item_name（标题）
  • brand（品牌）
  • size/color（尺码/颜色，服饰类核心属性）
  • list_price（价格）
  • condition_type（商品状态）
  • 至少一张主图
  • 库存数量（通过Inventory API设置）
• 亚马逊后台的"Incomplete"状态会明确提示缺少的字段，可直接查看后台的错误提示信息。

3. 确保所有详情正确提交并显示的步骤 #

1. 修正Payload格式：删除重复的item_name和list_price字段，保证JSON格式合法；
2. 校验必填字段：通过Product Type Definition API获取APPAREL类的完整必填字段列表，逐一核对Payload是否包含所有mandatory字段；
3. 单独设置库存：调用Inventory API设置商品库存数量；
4. 验证图片可用性：测试图片URL是否能直接在浏览器打开，确认格式、分辨率符合亚马逊要求；
5. 查询Listing状态：提交后调用Listings API的getListing接口，检查返回的字段是否与提交内容一致；
6. 查看后台提示：亚马逊后台的"Incomplete"状态会列出具体缺失的字段，根据提示补充信息；
7. 等待数据同步：SP-API提交后，亚马逊后台数据可能存在延迟，等待1-2小时后再检查状态。

内容的提问来源于stack exchange，提问作者Zaheer Ahmad