亚马逊 9.28 强制新 Listing 属性：JSON feed 必填字段，不更新即 API 拒单 Listing 失效

亚马逊开发者文档更新了一则容易被忽略的公告：2026 年 9 月 28 日起，Listings Items API 与 JSON_LISTINGS_FEED 提交商品时，一批新属性变成必填。没提供值的调用会被直接拒掉——不是警告，是 INVALID。做接口上架的卖家要立刻查自己的链路。

适用范围：三条通道，只有一条被管

这则公告的标题是「September Updates to Listing Attribute Usage and Enumeration Values」，落点是 Listings Items API v2021-08-01 和 JSON_LISTINGS_FEED 这两个提交通道。判断自己是否在范围内，只要回答一个问题：你是不是通过 API 或 JSON feed 来创建/编辑带 offer 的商品？

公告给出的边界很清楚。受影响的是：使用上述通道创建或编辑「有 offer 的商品」的开发者，官方原文把范围写为「both private and public developers」——也就是自研团队和第三方 ERP/刊登工具都算。明确不受影响的是三类：product-only listings（仅商品、不带 offer 的刊登）、XSD feed 上传、传统 XML feed 上传。

这里必须提醒一个容易误判的点：「不受影响」不等于「安全」。亚马逊这几年一直在把传统的 flat-file 与 XML 上传方式往 JSON_LISTINGS_FEED 上收，这次豁免更像是给尚未迁移的卖家留的窗口期，而不是长期路线。所以如果你的店铺现在跑的是 XML，短期确实不用急着改代码，但迁移是方向性的。

至于具体涉及哪些站点、哪些 product type、哪些属性名，公告本身没有逐条列出，它指向了一份单独的「SP-API product metadata changes」清单。这一步不能省——不同站点的 product type 覆盖面不同，必须按自己的实际类目去比对，公告里没有的细节不要靠猜。

必填字段分两类：新增 required 与枚举值收窄

图片来源：Tuoi Tre News（越南《青年报》英文版，图片来源 REUTERS / Toby Shepheard） — 亚马逊履约中心内员工在货架工位前取放商品，展示仓储拣选作业场景（https://news.tuoitre.vn/amazon-unveils-new-ai-warehouse-robot-in-12-billion-europe-push-103260605105359382.htm）

公告把这次变更拆成两个动作，性质完全不同，处理方式也不一样。

第一类是 attribute usage 变更。 官方原文是要求开发者「provide values for the newly added attributes with required usage」——即新增了一些属性，并且这些属性被标记为 required。这类字段的特点是：没有值就是硬失败，你必须从商品资料里找出真实数据填进去。公告同时说明，对于标记为 optional usage 的属性，提供与否仍然是你的选择。

第二类是 enumeration values 变更。 官方表述是开发者「can choose to use an enumeration from the new list in the dropdown values」——如果新的枚举值更适合你卖的商品，可以选择使用。这一类目前是可选动作，但值得做：枚举收窄之后，旧的描述方式可能会逐渐不再被推荐，早一点对齐能减少后续返工。

需要特别说明的是，这两种变更不能混为一谈。必填字段是「不填就报错」的硬门槛；枚举值更接近「有更贴切选项就用新选项」的软引导。把两者分开排期，才不会让枚举对齐这件事挤占必填字段的工时。

另外有一个操作层面的判断原则值得记住：枚举里有这个选项，不代表这个选项对你这件商品是真的。字段值首先要符合商品的真实规格，其次才是能不能选。为了「凑满」一份看起来完整的 payload 而选一个不符合实物的枚举值，是把接口问题变成了商品信息不实的问题，风险更大。

拒单与失效的判定链路：同步 reject 在前，异步问题在后

这是整件事最需要搞清楚的机制。亚马逊对提交内容做多轮校验，问题分同步和异步两种返回方式，两者的表现和处理动作完全不同。

同步问题发生在初始请求阶段——服务器在这一次请求里就把提交拒掉了，不会进入后续处理。按亚马逊官方的《商品信息 API 问题排查》文档，这类问题「很可能是与请求附加的属性不正确或参数处理不当有关」。必填属性缺失就属于典型的同步问题。对应的错误码是 90220，官方描述为「attribute_name 为必填项，但未提供」，并给出的预防措施是「使用商品类型定义 API 来确定所需的属性并添加到验证检查中」。

异步问题则是另一条链路：如果提交通过了前面的同步验证，提交会被接受并发送到下游去创建或更新 SKU，然后在亚马逊目录中完成创建还需要走多个下游流程，这些流程中的任何一个都可能生成异步返回的问题。异步问题的返回形式是「信息」，需要你订阅 LISTINGS_ITEM_STATUS_CHANGE 或 LISTINGS_ITEM_ISSUES_CHANGE 通知，或者用 getListingsItem / searchListingsItems 带 includedData=issues 参数主动读取，才能拿到。

把两条链路连起来看，「先 warning 还是直接 reject」的答案是：必填属性缺失走的是同步 reject，不会有 warning 缓冲。返回体里会给到 INVALID 状态和具体的问题描述（含缺失的属性名），但这次调用本身已经失败了。

至于 Listing 失效，正确的理解是它不是一个独立的处罚动作，而是提交失败的结果。如果创建/编辑没能成功，且这个过程是由自动化流程（比如改价、改库存、批量刊登）触发的静默失败，SKU 就会一直停留在旧状态；对于尚未成功建立的 listing，则表现为该商品没有进入目录。风险点在于高并发的自动化流程——失败是静默的，你不会收到一封邮件，只能靠日志或目录状态回查发现。

恢复路径与按类目分批的更新排期

恢复路径分四步，顺序不能颠倒。

第一步：先定位受影响集合。 调用 getDefinitionsProductType（product type definitions API）拉取你每个 product type 的最新 JSON Schema，注意要缓存 schema 并订阅 PRODUCT_TYPE_DEFINITIONS_CHANGE 通知——官方明确说明这个通知会在出现新的 product type 或新版本时发出，schema 是会变的，缓存不能只做一次。然后用你实际的商品记录（站点 × product type × 提交通道 × 责任人）去比对新旧 schema，把「确认受影响 / 确认不受影响 / 待确认」三类分开。这一栏留空的任务，不叫不受影响，叫没查。

第二步：本地预校验，别把失败留给线上。 官方流程引导开发者「在提交前使用 JSON Schema validation utilities 检查listing 数据是否满足要求」。这一步的意义是把 reject 拦在生产环境之外。

第三步：修改 payload 构建逻辑并发起提交。 补齐 required 属性、按需切换到更贴切的新枚举值，然后提交。同步 INVALID 的情况下，修正问题后直接重新提交即可；如果问题报告来自异步通知，则按通知里指出的问题项修正 JSON 后再重试。

第四步：闭环核验。 提交后检查返回是不是 ACCEPTED，再通过 getListingsItem 或目录状态确认 SKU 真的生效了。收到 ACCEPTED 只代表通过初步校验并已送往下游，不等于目录创建已经完成。

排期建议：按类目分批，先窄后宽。 不要一次性全量改。推荐的批次顺序是：第一批先做必填字段缺失风险最高的类目（通常是属性维度多的品类，比如服装、电子、家居建材）；第二批做已有第三方刊登工具在跑的类目——这类要先和工具方确认他们的更新计划，你的时间表受制于别人；第三批做 XML/XSD 通道的类目，把它们作为后续迁移 JSON 的预备工作同步推进。每一批都要有明确的负责人和决定日期，无法在窗口内解决的依赖，写成带责任人的未决项，别留在空白格里。

注意事项

第一，先分清你的提交通道，再谈改什么。 三条通道只有一条被管，如果你的店铺走的是 XML 或 XSD，这次的紧急程度完全不同。但请把「排查」和「整改」分开：即使不受影响，也值得顺手确认自己的 product type schema 缓存机制是否健康，因为下次公告的覆盖面可能就包括你。不确定的条目写成待查，不要凭类目名字听起来像就直接判定受影响，也不要凭「我们一直没事」就判定不受影响。

第二，警惕静默失败，尤其是自动化链路。 必填属性缺失是同步 reject，不会给 warning。如果你的改价、改库存、批量刊登是脚本在跑，请务必在流程里加一层失败告警；另外，官方文档提到要订阅 LISTINGS_ITEM_STATUS_CHANGE 和 LISTINGS_ITEM_ISSUES_CHANGE 通知才能收到异步问题，没订阅就等于收不到，这一点最容易被漏掉。第三方工具同理——先问清楚对方是否已经适配，你的 listing 稳定性取决于他们的排期。

第三，填值前先确认商品事实。 补齐 required 属性的过程中，最容易出的错是为了让 payload 通过而填一个「看起来对」的值。不要把「字段需要值」「这个值被允许」「这个值符合实物」三件事混在一次判断里。 真值缺失的，交给维护商品规格或供应商资料的人，把证据和拟填值一起留存。如果订阅了通知还是定位不到具体是哪个 product type 触发的 reject，可以带着卖家编号、提交编号截图、准确的品牌名与 UPC/EAN 信息向亚马逊 Developer Support 提交案例。

FAQ

Q：这次变更是「警告」还是直接拒绝提交？ A：必填属性缺失属于同步问题，会在初始请求阶段直接把提交拒掉，不会先给 warning。亚马逊官方文档对同步问题的定义是「服务器在初始请求期间拒绝请求」，典型错误码是 90220（属性为必填项但未提供）。另外还有一类异步问题，是提交通过同步校验后、在下游处理阶段才返回的，需要通过通知或读取接口获取。

Q：我只用 XML feed / XSD 上传，需要处理吗？ A：本次变更明确不覆盖 product-only listings、XSD feed 上传和传统 XML feed 上传。但亚马逊长期方向是把传统上传方式往 JSON_LISTINGS_FEED 迁移，建议把这条通道的迁移作为后续工作项排进去。

Q：发现提交被拒之后，应该怎么恢复？ A：先调用 product type definitions API 确认对应 product type 的最新 schema 与 required 属性列表，在本地用 JSON Schema 校验工具预校验，修正 payload 后重新提交。提交后确认返回为 ACCEPTED，再通过 getListingsItem 或目录状态确认 SKU 已正常生效；若是异步问题，按通知中指出的问题项修正后重试。

参考来源

• Amazon Selling Partner API 开发者文档：《September Updates to Listing Attribute Usage and Enumeration Values》
• Amazon Selling Partner API 开发者文档：《商品信息 API 问题排查》（Listings Items API Issues Troubleshooting）
• Amazon Selling Partner API 开发者文档：《Building Listings Management Workflows Guide》
• Amazon Selling Partner API 开发者文档：SP-API product metadata changes 清单（公告指向的受影响站点与 product type 明细）
• EcomWatch：《Amazon Forces API Overhaul As New Listing Attributes Go Live For Sellers》
• Amalert：《September Updates to Listing Attribute Usage and Enumeration Values》
• Tmark.pro：《Prepare Your Amazon Listing Data for September 28》