This skill and linkfox-amazon-store-auth、linkfox-amazon-store-report both belong to the Amazon Store series: depends on linkfox-amazon-store-auth store selection (sellerId+region); directly POST /spApi/developerProxy pass in sellerId+region, the server parses the token (do not pass amzAccessToken, unless for compatibility with legacy calls). Forward upstream GET、PATCH、PUT or DELETE。
| Operations | Official reference |
|---|---|
| Single listing | getListingsItem |
| Search list | searchListingsItems |
| Partially update listing | patchListingsItem |
| Create / fully update listing | putListingsItem |
| Delete listing | deleteListingsItem |
| Listing restrictions (ASIN) | getListingsRestrictions |
| Search product type | searchDefinitionsProductTypes |
| Get product type definition | getDefinitionsProductType |
How to call
- API endpoint：
POST /spApi/developerProxy(different operations are distinguished by the request body; for complete parameters/responses/error codes seereferences/api.md） - Python script：
python scripts/<脚本名>.py '<JSON 参数>' [--inline](available scripts are listed in the script overview above) - Cost constraint: This tool consumes compute; on failure/empty results, do not automatically switch keywords, paginate, or repeatedly probe; if you need to continue searching, first explain to the user that additional consumption will be incurred.
Output strategy (default script behavior)：
- Alwayswrite the complete response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json（<cwd>is the working directory when the script is executed, which in Claude Code is the current project directory;<session>is taken from the environment variableSESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, if the current directory is not writable, report an error) - Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
- Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as
total/costToken, length of the largest list field + first 3 samples) - Add
--inlineto force full printing to stdout (also written to disk)
Data reading suggestions: first look at the summary to judge whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-JsonorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.
Resolve authentication and compute issues
When the following abnormal situations occur, use references/onboarding.md to guide resolution:
Abnormal situations
- API Key not configured: the environment variable is not configured
LINKFOX_AGENT_API_KEY, andLINKFOXAGENT_API_KEY。 - Response 401 or 402 status code
- Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with similar meaning.
Prerequisites (must read first)
This skill depends on linkfox-amazon-store-auth. The process is the same as linkfox-amazon-store-report :
- Run
python scripts/check_auth_dependency.py; if exit code 42 and stderr containsDEPENDENCY_MISSING:, please first installlinkfox-amazon-store-auth。 - Do notBypass dependency implementation authorization or token logic within this skill.
Current Capabilities
| Capability | Path key points | Script |
|---|---|---|
| Get a single Listing | listings/2021-08-01/items/{sellerId}/{sku} + Query |
scripts/get_listings_item.py |
| Search listings | listings/2021-08-01/items/{sellerId} + Query（Nonepath trailing segment SKU) |
scripts/search_listings_items.py |
| Partially update Listing (PATCH) | Same as get path + Query + JSON body | scripts/patch_listings_item.py |
| Create / full update Listing (PUT) | Same as get path + Query + body;marketplaceIds only 1 | scripts/put_listings_item.py |
| Delete Listing (DELETE) | Same as get path + Query (marketplaceIds only 1） | scripts/delete_listings_item.py |
| Listing restrictions | listings/2021-08-01/restrictions + Query (asin, sellerId, marketplaceIds, etc.) |
scripts/get_listings_restrictions.py |
| Search Product Type | definitions/2020-09-01/productTypes + Query |
scripts/search_definitions_product_types.py |
| Get Product Type definition | definitions/2020-09-01/productTypes/{productType} + Query；marketplaceIds only 1 |
scripts/get_definitions_product_type.py |
searchListingsItems under identifiers / variationParentSku / packageHierarchySku the three are mutually exclusive(only this interface; see references/api.md）。searchDefinitionsProductTypes under keywords and itemName mutually exclusive。
Quick Parameters
getListingsItem (single)
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Authorized Seller ID |
| region | Yes | NA / EU / FE |
| sku | Yes | Seller SKU(not ASIN) |
| marketplaceIds | Yes | Recommended only one marketplace id |
| includedData / issueLocale | No | See references/api.md |
searchListingsItems (list)
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Authorized Seller ID |
| region | Yes | NA / EU / FE |
| marketplaceIds | Yes | Recommended only one marketplace id |
| identifiers + identifiersType | No | At most 20 items; with variationParentSku、packageHierarchySku cannot be used together |
| variationParentSku / packageHierarchySku | No | With identifiers mutually exclusive |
| Time window / status / sort / pagination | No | createdAfter、lastUpdatedBefore、withStatus、sortBy、pageSize（≤20）、pageToken etc., see references/api.md |
patchListingsItem (partial update)
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Authorized Seller ID |
| region | Yes | NA / EU / FE |
| sku | Yes | Seller SKU |
| marketplaceIds | Yes | Array or comma-separated string; the script concatenates into Query |
| productType | Yes | Amazon product type |
| patches | Yes | At least 1 item JSON Patch（op、path etc.) |
| includedData / mode / issueLocale | No | See references/api.md |
putListingsItem (create / full update)
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Authorized Seller ID |
| region | Yes | NA / EU / FE |
| sku | Yes | Seller SKU |
| marketplaceIds | Yes | Exactly one marketplace id |
| productType | Yes | Amazon product type |
| requirements | Yes | LISTING | LISTING_PRODUCT_ONLY | LISTING_OFFER_ONLY |
| attributes | Yes | Must conform to that product type schema |
| includedData / mode / issueLocale | No | See references/api.md |
deleteListingsItem (Delete)
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Authorized Seller ID |
| region | Yes | NA / EU / FE |
| sku | Yes | Seller SKU |
| marketplaceIds | Yes | Exactly one marketplace id |
| issueLocale | No | See references/api.md |
getListingsRestrictions
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Used for storeTokens and Query |
| region | Yes | NA / EU / FE |
| asin | Yes | Catalog ASIN |
| marketplaceIds | Yes | Array or comma-separated string |
| conditionType / reasonLocale | No | See references/api.md |
searchDefinitionsProductTypes
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Used for storeTokens |
| region | Yes | NA / EU / FE |
| marketplaceIds | Yes | Array or comma-separated string |
| keywords or itemName | No | The two cannot be passed at the same time(mutually exclusive when non-empty) |
| locale / searchLocale | No | See references/api.md |
getDefinitionsProductType
| Field | Required | Description |
|---|---|---|
| sellerId | Yes | Used for storeTokens |
| region | Yes | NA / EU / FE |
| productType | Yes | e.g., LUGGAGE(write to path) |
| marketplaceIds | Yes | Exactly one id |
| querySellerId | No | If the upstream Query sellerId(seller-specific schema) is needed, pass it in; often the same as sellerId is the same |
| productTypeVersion / requirements / requirementsEnforced / locale | No | See references/api.md |
Scripts
scripts/get_listings_item.py— single listing.scripts/search_listings_items.py— search listings.scripts/patch_listings_item.py— PATCH partial update.scripts/put_listings_item.py— PUT create or full update.scripts/delete_listings_item.py— DELETE delete listing.scripts/get_listings_restrictions.py— GET listing restrictions.scripts/search_definitions_product_types.py— GET search product type.scripts/get_definitions_product_type.py— GET product type JSON Schema。scripts/check_auth_dependency.py— dependency check.
Example:
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 class APIs: when the path contains Seller SKU , emphasize that it is not an ASIN;searchListingsItems path only goes to
sellerId。 - When displaying gateway results, explain
errcode/httpStatus; after success, then parsebody（listing/searchResult/patchResult/putResult/deleteResult/restrictionsResult/productTypesSearchResult/productTypeDefinitionResult）。 - searchListingsItems multiple pages: get the next page token from
searchResult(field name is subject to the Amazon response), pass it inpageToken。 - restrictions / definitions path is different from items different;1005 when
listings/2021-08-01/restrictionsanddefinitions/2020-09-01/productTypesand other prefixes must have whitelists configured separately (subject to operations). - patch / put / delete is a write operation;delete must be used with caution;put is a full
attributes；patch only top-level attributes can be patched (subject to official documentation).
Important Limitations
- marketplaceIds：get / searchListingsItems script often takes only the first for multiple ids;put / delete / getDefinitionsProductType more than 1 will cause an error;patch、restrictions、searchDefinitionsProductTypes behavior see
references/api.md。 - searchListingsItems：
pageSize≤ 20；identifiers≤ 20。 - patch：
patchesat least 1 entry; JSON Patch'sdeleteand deleteListingsItem APIs are different; Vendor may 400。 - put：LISTING_OFFER_ONLY for Vendor 400。
- Whitelist：
listings/.../items、listings/.../restrictions、definitions/2020-09-01/productTypesmust all be allowed as needed.
Amazon SP-API Interface Protection and Retry Guidelines
When the same store continuously receives 400, 403, 404, or 429 from Amazon SP-API, the gateway returns 450, 453, 454, or 459 and briefly cools down. These custom status codes are not native Amazon statuses and do not indicate account suspension; the purpose is to avoid continuous anomalies or high-frequency calls increasing store risk.
| Status and message | Scope | Trigger and cooldown | Handling |
|---|---|---|---|
450：400，请求异常，请优化您的参数 |
Store + interface | More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 20 minutes | Stop retrying with the original parameters, and check required fields, marketplace, ID, date, and request body |
453：403，店铺未授权，请先授权 |
All store interfaces | More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes | Stop calling for that store, and check authorization, permissions, store ownership, and region |
454：404，资源不存在，请优化您的参数 |
Store + interface | More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes | Confirm the resource ID, owning store/site, resource status, and interface path |
459：429限流中，请降低频率 |
Store + interface | First time: 15 seconds; more than 2 times within 2 minutes: 30 seconds; more than 4 times within 3 minutes: 2 minutes | Reduce concurrency, pagination, and polling frequency, and back off step by step |
- Immediately stop automatic or concurrent retries; do not bypass protection by switching scripts or repeatedly creating tasks; prioritize following
retryAfter、blockedUntil, and when there is none, follow the duration descriptions in the table. - For 450/453/454, you must first correct the parameters, authorization, or resource identifier, and after cooldown retry cautiously at most once; if triggered again, stop calling. During 453, stop all SP-API for that store.
- Keep existing
reportId、feedIdand other task IDs; when the result of a write operation is uncertain, query the status first and do not directly replay. - First explain store protection to the user, then give the reason, handling, and waiting time. You may reply: "To protect the security of your Amazon store, continuous returns of {reason} from Amazon SP-API have been detected, and a brief protection period is currently in effect. Please first {handling action}, and try again after an estimated {waiting time}; this does not indicate account suspension, nor is it a plan or computing power limit." Do not only say "LinkFox rate limiting" or "server busy."
Computing power consumption rules
No computing power is consumed.
Feedback： See references/api.md Feedback API inskillName：linkfox-amazon-store-listings。
More cross-border skills:LinkFox Skills