linkfox-amazon-store-listings

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Amazon 店铺 Listings 与相关 API

Amazon店铺Listings及相关API

本 skill 与 linkfox-amazon-store-auth
、linkfox-amazon-store-report
同属 Amazon Store 系列：使用 POST /spApi/storeTokens
取

accessToken

，再经 POST /spApi/developerProxy
转发上游 GET、PATCH、PUT 或 DELETE。

操作	官方参考
单条刊登	getListingsItem
检索列表	searchListingsItems
部分更新刊登	patchListingsItem
创建 / 全量更新刊登	putListingsItem
删除刊登	deleteListingsItem
刊登限制（ASIN）	getListingsRestrictions
搜索 product type	searchDefinitionsProductTypes
获取 product type 定义	getDefinitionsProductType

本skill与 linkfox-amazon-store-auth
、linkfox-amazon-store-report
同属 Amazon Store 系列：使用 POST /spApi/storeTokens
获取

accessToken

，再通过 POST /spApi/developerProxy
转发上游的 GET、PATCH、PUT 或 DELETE 请求。

操作	官方参考
单条刊登	getListingsItem
检索列表	searchListingsItems
部分更新刊登	patchListingsItem
创建/全量更新刊登	putListingsItem
删除刊登	deleteListingsItem
刊登限制（ASIN）	getListingsRestrictions
搜索product type	searchDefinitionsProductTypes
获取product type定义	getDefinitionsProductType

Prerequisites（必须先读）

前置条件（必须阅读）

本 skill 依赖 linkfox-amazon-store-auth
。流程与

linkfox-amazon-store-report

相同：

运行

python scripts/check_auth_dependency.py

；若 exit code 42 且 stderr 含

DEPENDENCY_MISSING:

，请先安装 linkfox-amazon-store-auth
。

不要在本 skill 内绕过依赖实现授权或令牌逻辑。

本skill 依赖 linkfox-amazon-store-auth
。流程与

linkfox-amazon-store-report

相同：

运行

python scripts/check_auth_dependency.py

；若退出码为 42 且标准错误流包含

DEPENDENCY_MISSING:

，请先安装 linkfox-amazon-store-auth
。

请勿在本skill内绕过依赖实现授权或令牌逻辑。

Current Capabilities

当前功能

能力	Path 要点	脚本
获取单条 Listing	`listings/2021-08-01/items/{sellerId}/{sku}` + Query	`scripts/get_listings_item.py`
搜索刊登列表	`listings/2021-08-01/items/{sellerId}` + Query（无路径尾段 SKU）	`scripts/search_listings_items.py`
部分更新 Listing（PATCH）	同 get 路径 + Query + JSON body	`scripts/patch_listings_item.py`
创建 / 全量更新 Listing（PUT）	同 get 路径 + Query + body；marketplaceIds 仅 1 个	`scripts/put_listings_item.py`
删除 Listing（DELETE）	同 get 路径 + Query（marketplaceIds 仅 1 个）	`scripts/delete_listings_item.py`
刊登限制	`listings/2021-08-01/restrictions` + Query（asin、sellerId、marketplaceIds 等）	`scripts/get_listings_restrictions.py`
搜索 Product Type	`definitions/2020-09-01/productTypes` + Query	`scripts/search_definitions_product_types.py`
获取 Product Type 定义	`definitions/2020-09-01/productTypes/{productType}` + Query；marketplaceIds 仅 1 个	`scripts/get_definitions_product_type.py`

searchListingsItems 下

identifiers

variationParentSku

packageHierarchySku

三者互斥（仅该接口；见 references/api.md
）。searchDefinitionsProductTypes 下 keywords
与 itemName
互斥。

能力	Path要点	脚本
获取单条Listing	`listings/2021-08-01/items/{sellerId}/{sku}` + 查询参数	`scripts/get_listings_item.py`
搜索刊登列表	`listings/2021-08-01/items/{sellerId}` + 查询参数（无路径末尾的SKU）	`scripts/search_listings_items.py`
部分更新Listing（PATCH）	与get路径相同 + 查询参数 + JSON请求体	`scripts/patch_listings_item.py`
创建/全量更新Listing（PUT）	与get路径相同 + 查询参数 + 请求体；marketplaceIds仅支持1个	`scripts/put_listings_item.py`
删除Listing（DELETE）	与get路径相同 + 查询参数（marketplaceIds仅支持1个）	`scripts/delete_listings_item.py`
刊登限制	`listings/2021-08-01/restrictions` + 查询参数（asin、sellerId、marketplaceIds等）	`scripts/get_listings_restrictions.py`
搜索Product Type	`definitions/2020-09-01/productTypes` + 查询参数	`scripts/search_definitions_product_types.py`
获取Product Type定义	`definitions/2020-09-01/productTypes/{productType}` + 查询参数；marketplaceIds仅支持1个	`scripts/get_definitions_product_type.py`

searchListingsItems 接口下的

identifiers

variationParentSku

packageHierarchySku

三者互斥（仅该接口有此限制；详见 references/api.md
）。searchDefinitionsProductTypes 接口下的 keywords
与 itemName
互斥。

Quick Parameters

快速参数说明

getListingsItem（单条）

getListingsItem（单条刊登）

字段	必填	说明
sellerId	是	已授权 Seller ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家 SKU（非 ASIN）
marketplaceIds	是	建议仅一个 marketplace id
includedData / issueLocale	否	见 `references/api.md`

字段	必填	说明
sellerId	是	已授权的卖家ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家SKU（非ASIN）
marketplaceIds	是	建议仅传一个marketplace ID
includedData / issueLocale	否	详见 `references/api.md`

searchListingsItems（列表）

searchListingsItems（刊登列表搜索）

字段	必填	说明
sellerId	是	已授权 Seller ID
region	是	`NA` / `EU` / `FE`
marketplaceIds	是	建议仅一个 marketplace id
identifiers + identifiersType	否	最多 20 个；与 `variationParentSku` 、 `packageHierarchySku` 不能同用
variationParentSku / packageHierarchySku	否	与 identifiers 互斥
时间窗 / 状态 / 排序 / 分页	否	`createdAfter` 、 `lastUpdatedBefore` 、 `withStatus` 、 `sortBy` 、 `pageSize` （≤20）、 `pageToken` 等，见 `references/api.md`

字段	必填	说明
sellerId	是	已授权的卖家ID
region	是	`NA` / `EU` / `FE`
marketplaceIds	是	建议仅传一个marketplace ID
identifiers + identifiersType	否	最多 20 个；不可与 `variationParentSku` 、 `packageHierarchySku` 同时使用
variationParentSku / packageHierarchySku	否	与identifiers 互斥
时间窗/状态/排序/分页	否	`createdAfter` 、 `lastUpdatedBefore` 、 `withStatus` 、 `sortBy` 、 `pageSize` （≤20）、 `pageToken` 等，详见 `references/api.md`

patchListingsItem（部分更新）

字段	必填	说明
sellerId	是	已授权 Seller ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家 SKU
marketplaceIds	是	数组或逗号字符串；脚本拼入 Query
productType	是	Amazon product type
patches	是	至少 1 条 JSON Patch（ `op` 、 `path` 等）
includedData / mode / issueLocale	否	见 `references/api.md`

字段	必填	说明
sellerId	是	已授权的卖家ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家SKU
marketplaceIds	是	数组或逗号分隔的字符串；脚本会将其拼入查询参数
productType	是	Amazon product type
patches	是	至少1条JSON Patch（包含 `op` 、 `path` 等字段）
includedData / mode / issueLocale	否	详见 `references/api.md`

putListingsItem（创建 / 全量更新）

putListingsItem（创建/全量更新）

字段	必填	说明
sellerId	是	已授权 Seller ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家 SKU
marketplaceIds	是	恰好一个 marketplace id
productType	是	Amazon product type
requirements	是	`LISTING` \| `LISTING_PRODUCT_ONLY` \| `LISTING_OFFER_ONLY`
attributes	是	须符合该 product type schema
includedData / mode / issueLocale	否	见 `references/api.md`

字段	必填	说明
sellerId	是	已授权的卖家ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家SKU
marketplaceIds	是	恰好一个marketplace ID
productType	是	Amazon product type
requirements	是	`LISTING` \| `LISTING_PRODUCT_ONLY` \| `LISTING_OFFER_ONLY`
attributes	是	必须符合该product type的schema
includedData / mode / issueLocale	否	详见 `references/api.md`

deleteListingsItem（删除）

deleteListingsItem（删除刊登）

字段	必填	说明
sellerId	是	已授权 Seller ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家 SKU
marketplaceIds	是	恰好一个 marketplace id
issueLocale	否	见 `references/api.md`

字段	必填	说明
sellerId	是	已授权的卖家ID
region	是	`NA` / `EU` / `FE`
sku	是	卖家SKU
marketplaceIds	是	恰好一个marketplace ID
issueLocale	否	详见 `references/api.md`

getListingsRestrictions

字段	必填	说明
sellerId	是	用于 `storeTokens` 与 Query
region	是	`NA` / `EU` / `FE`
asin	是	目录 ASIN
marketplaceIds	是	数组或逗号字符串
conditionType / reasonLocale	否	见 `references/api.md`

字段	必填	说明
sellerId	是	用于 `storeTokens` 和查询参数
region	是	`NA` / `EU` / `FE`
asin	是	目录ASIN
marketplaceIds	是	数组或逗号分隔的字符串
conditionType / reasonLocale	否	详见 `references/api.md`

searchDefinitionsProductTypes

字段	必填	说明
sellerId	是	用于 `storeTokens`
region	是	`NA` / `EU` / `FE`
marketplaceIds	是	数组或逗号字符串
keywords 或 itemName	否	二者不可同时传（非空时互斥）
locale / searchLocale	否	见 `references/api.md`

字段	必填	说明
sellerId	是	用于 `storeTokens`
region	是	`NA` / `EU` / `FE`
marketplaceIds	是	数组或逗号分隔的字符串
keywords 或 itemName	否	二者不可同时传入（非空时互斥）
locale / searchLocale	否	详见 `references/api.md`

getDefinitionsProductType

字段	必填	说明
sellerId	是	用于 `storeTokens`
region	是	`NA` / `EU` / `FE`
productType	是	如 `LUGGAGE` （写入 path）
marketplaceIds	是	恰好一个 id
querySellerId	否	若需上游 Query `sellerId` （卖家专属 schema），传入；常与 `sellerId` 相同
productTypeVersion / requirements / requirementsEnforced / locale	否	见 `references/api.md`

字段	必填	说明
sellerId	是	用于 `storeTokens`
region	是	`NA` / `EU` / `FE`
productType	是	例如 `LUGGAGE` （写入路径）
marketplaceIds	是	恰好一个ID
querySellerId	否	若需上游查询参数 `sellerId` （卖家专属schema），则传入；通常与 `sellerId` 相同
productTypeVersion / requirements / requirementsEnforced / locale	否	详见 `references/api.md`

Scripts

脚本说明

scripts/get_listings_item.py
— 单条 listing。
scripts/search_listings_items.py
— 搜索列表。
scripts/patch_listings_item.py
— PATCH 部分更新。
scripts/put_listings_item.py
— PUT 创建或全量更新。
scripts/delete_listings_item.py
— DELETE 删除刊登。
scripts/get_listings_restrictions.py
— GET 刊登限制。

scripts/search_definitions_product_types.py
— GET 搜索 product type。

scripts/get_definitions_product_type.py
— GET product type JSON Schema。
scripts/check_auth_dependency.py
— 依赖检测。

示例：

bash

export LINKFOXAGENT_API_KEY="<your-key>"

python scripts/get_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"]}'

python scripts/search_listings_items.py '{"sellerId":"A1...","region":"NA","marketplaceIds":["ATVPDKIKX0DER"],"identifiers":["B0XXXXXXXX"],"identifiersType":"ASIN"}'

python scripts/patch_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"],"productType":"LUGGAGE","patches":[{"op":"replace","path":"/attributes/item_name","value":[{"value":"New Title","marketplace_id":"ATVPDKIKX0DER"}]}]}'

python scripts/put_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"],"productType":"LUGGAGE","requirements":"LISTING","attributes":{"item_name":[{"value":"Title","marketplace_id":"ATVPDKIKX0DER"}]}}'

python scripts/delete_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"]}'

python scripts/get_listings_restrictions.py '{"sellerId":"A1...","region":"NA","asin":"B0XXXXXXXX","marketplaceIds":["ATVPDKIKX0DER"]}'

python scripts/search_definitions_product_types.py '{"sellerId":"A1...","region":"NA","marketplaceIds":["ATVPDKIKX0DER"],"keywords":["luggage"]}'

python scripts/get_definitions_product_type.py '{"sellerId":"A1...","region":"NA","productType":"LUGGAGE","marketplaceIds":["ATVPDKIKX0DER"],"querySellerId":"A1..."}'

scripts/get_listings_item.py
— 获取单条Listing。
scripts/search_listings_items.py
— 搜索刊登列表。
scripts/patch_listings_item.py
— 通过PATCH部分更新刊登。
scripts/put_listings_item.py
— 通过PUT创建或全量更新刊登。
scripts/delete_listings_item.py
— 通过DELETE删除刊登。
scripts/get_listings_restrictions.py
— 获取刊登限制。

scripts/search_definitions_product_types.py
— 搜索product type。

scripts/get_definitions_product_type.py
— 获取product type的JSON Schema。
scripts/check_auth_dependency.py
— 依赖检测。

示例：

bash

export LINKFOXAGENT_API_KEY="<your-key>"

python scripts/get_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"]}'

python scripts/search_listings_items.py '{"sellerId":"A1...","region":"NA","marketplaceIds":["ATVPDKIKX0DER"],"identifiers":["B0XXXXXXXX"],"identifiersType":"ASIN"}'

python scripts/patch_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"],"productType":"LUGGAGE","patches":[{"op":"replace","path":"/attributes/item_name","value":[{"value":"New Title","marketplace_id":"ATVPDKIKX0DER"}]}]}'

python scripts/put_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"],"productType":"LUGGAGE","requirements":"LISTING","attributes":{"item_name":[{"value":"Title","marketplace_id":"ATVPDKIKX0DER"}]}}'

python scripts/delete_listings_item.py '{"sellerId":"A1...","region":"NA","sku":"MY-SKU","marketplaceIds":["ATVPDKIKX0DER"]}'

python scripts/get_listings_restrictions.py '{"sellerId":"A1...","region":"NA","asin":"B0XXXXXXXX","marketplaceIds":["ATVPDKIKX0DER"]}'

python scripts/search_definitions_product_types.py '{"sellerId":"A1...","region":"NA","marketplaceIds":["ATVPDKIKX0DER"],"keywords":["luggage"]}'

python scripts/get_definitions_product_type.py '{"sellerId":"A1...","region":"NA","productType":"LUGGAGE","marketplaceIds":["ATVPDKIKX0DER"],"querySellerId":"A1..."}'

Display Rules

展示规则

items 类接口：路径含 卖家 SKU 时强调非 ASIN；searchListingsItems 路径仅到
```
sellerId
```
。

展示网关结果时说明 errcode
/
httpStatus
；成功后再解析

body

（

listing

searchResult

patchResult

putResult

deleteResult

/ restrictionsResult
/ productTypesSearchResult
/ productTypeDefinitionResult
）。

searchListingsItems 多页：从
```
searchResult
```
取下一页 token（字段名以 Amazon 响应为准），传入
```
pageToken
```
。
restrictions / definitions 路径与 items 不同；1005 时需为 listings/2021-08-01/restrictions
与 definitions/2020-09-01/productTypes
等前缀分别配置白名单（以运维为准）。
patch / put / delete 为写操作；delete 须谨慎；put 为全量 attributes
；patch 仅顶层属性可 patch（以官方为准）。

items类接口：路径包含卖家SKU时需强调其非ASIN；searchListingsItems的路径仅到
```
sellerId
```
。

展示网关结果时需说明 errcode
/
httpStatus
；请求成功后再解析

body

（

listing

searchResult

patchResult

putResult

deleteResult

/ restrictionsResult
/ productTypesSearchResult
/ productTypeDefinitionResult
）。

searchListingsItems多页处理：从
```
searchResult
```
中获取下一页的token（字段名以Amazon响应为准），传入
```
pageToken
```
参数。
restrictions / definitions的路径与items不同；当出现错误码1005时，需为 listings/2021-08-01/restrictions
与 definitions/2020-09-01/productTypes
等前缀分别配置白名单（以运维要求为准）。
patch / put / delete为写操作；delete操作需谨慎；put操作会全量更新**
```
attributes
```
**；patch仅支持顶层属性的更新（以官方文档为准）。

Important Limitations

重要限制

marketplaceIds：get / searchListingsItems 脚本对多 id 常仅取第一个；put / delete / getDefinitionsProductType 多于 1 个即报错；patch、restrictions、searchDefinitionsProductTypes 行为见 references/api.md
。
searchListingsItems：
```
pageSize
```
≤ 20；
```
identifiers
```
≤ 20。
patch：
```
patches
```
至少 1 条；JSON Patch 的 delete
与 deleteListingsItem 接口不同；Vendor 对部分 patch 可能 400。
put：LISTING_OFFER_ONLY 对 Vendor 400。

白名单：

listings/.../items

、

listings/.../restrictions

、

definitions/2020-09-01/productTypes

均须按需放行。

Feedback： 见

references/api.md

中 Feedback API，

skillName

：

linkfox-amazon-store-listings

。

更多跨境 skill：LinkFox Skills

marketplaceIds：get / searchListingsItems脚本对多个ID通常仅取第一个；put / delete / getDefinitionsProductType传入超过1个ID会直接报错；patch、restrictions、searchDefinitionsProductTypes的行为详见 references/api.md
。
searchListingsItems：
```
pageSize
```
≤ 20；
```
identifiers
```
≤ 20。
patch：
```
patches
```
至少需要1条；JSON Patch中的**
```
delete
```
操作与deleteListingsItem接口的删除操作不同；Vendor账号对部分patch操作可能返回400**错误。
put：LISTING_OFFER_ONLY类型对Vendor账号会返回400错误。

白名单：

listings/.../items

、

listings/.../restrictions

、

definitions/2020-09-01/productTypes

均需按需配置放行。

反馈： 详见

references/api.md

中的Feedback API，

skillName

为：

linkfox-amazon-store-listings

。

更多跨境skill：LinkFox Skills

Handling Large Responses

大响应处理

To avoid overflowing the agent context, persist the response to disk and extract only the fields you need:

python scripts/response_io.py run --script scripts/check_auth_dependency.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

Pick
--out-dir
outside any git working tree (e.g.
/tmp/...
on Unix,
%TEMP%/...
on Windows). Persisted responses may contain PII, pricing, or auth-sensitive data — do not commit them. Files are not auto-deleted; clean up when the task is done.

This skill exposes multiple entry scripts:

check_auth_dependency.py

delete_listings_item.py

get_definitions_product_type.py

get_listings_item.py

get_listings_restrictions.py

patch_listings_item.py

put_listings_item.py

search_definitions_product_types.py

search_listings_items.py

. Pass

--script scripts/<name>.py

to choose the one you need.

run

writes the full response to a file and emits only a schema preview + file path.

read

projects specific fields, with

--limit/--offset

for slicing and

--format json|jsonl|csv|table

for output.

When to prefer this pattern — apply your judgment based on the response characteristics, e.g.:

High field count per record, or fields you don't need
Batch/paginated results (multiple items per call)
Long-text fields (descriptions, reviews, HTML, time series)
Output reused across later steps rather than consumed immediately

For small, single-use responses, calling the main script directly is fine.

⚠️ The preview is a truncated schema + sample, not the full data. Any field-level decision must read from the persisted file via

read

为避免超出Agent上下文限制，可将响应持久化到磁盘并仅提取所需字段：

python scripts/response_io.py run --script scripts/check_auth_dependency.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # 或使用 --path "<JMESPath>"

请选择Git工作区外的
--out-dir
（例如Unix系统的
/tmp/...
，Windows系统的
%TEMP%/...
）。持久化的响应可能包含个人身份信息（PII）、定价或敏感授权数据——请勿提交到版本控制系统。文件不会自动删除，任务完成后请自行清理。

本skill提供多个入口脚本：

check_auth_dependency.py

、

delete_listings_item.py

、

get_definitions_product_type.py

、

get_listings_item.py

、

get_listings_restrictions.py

、

patch_listings_item.py

、

put_listings_item.py

、

search_definitions_product_types.py

、

search_listings_items.py

。通过

--script scripts/<name>.py

参数选择所需脚本。

run

命令会将完整响应写入文件，并仅输出schema预览+文件路径。

read

命令会提取指定字段，支持通过

--limit/--offset

进行切片，以及通过

--format json|jsonl|csv|table

指定输出格式。

何时优先使用此模式——根据响应特性判断，例如：

每条记录字段数量多，或包含不需要的字段
批量/分页结果（单次调用返回多条数据）
长文本字段（描述、评论、HTML、时间序列等）
输出结果需在后续步骤中重复使用，而非立即消费

对于小型、单次使用的响应，直接调用主脚本即可。

⚠️ 预览内容是截断的schema+示例，并非完整数据。任何字段级别的决策都必须通过

read

命令从持久化文件中读取。