SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-amazon-store-catalog

linkfox-amazon-store-catalog

Data & analytics

View repository

Updated 10-15 09:05

About this skill

Amazon Store Catalog Items

This skill, together with linkfox-amazon-store-auth , belongs to the same Amazon Store series: depends on linkfox-amazon-store-auth store selection (sellerId+region); directly POST /spApi/developerProxy pass in sellerId+region, and the server parses the token (do not pass amzAccessToken, unless compatible with legacy calls). Forward GET。

Invocation method

  • API endpoint：POST /spApi/developerProxy(different operations are distinguished via the request body; for complete parameters/responses/error codes see references/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 continuously probe; when further retrieval is needed, first explain to the user that it will incur additional consumption.

Output strategy (default script behavior)：

  • Alwayswrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-catalog-<timestamp>.json（<cwd> is the working directory when the script is executed; in Claude Code this is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user task;Writing to /tmp is prohibited, if the current directory is not writable, report an error)
  • Response body ≤ 8 KB: after saving to disk, print the full JSON to stdout
  • Response body > 8 KB: after saving to disk, stdout outputs only a summary (top-level fields, common counts such as total/costToken, the length of the largest list field + the first 3 samples)
  • Add --inline to force full printing to stdout (also saved to disk)

Data reading recommendations: First look at the summary to determine whether it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract as needed from the saved json file, avoiding loading the entire JSON into the context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide resolving the issue:

Abnormal situations

  • API Key not configured: environment variable not configured LINKFOX_AGENT_API_KEY, and also not configured LINKFOXAGENT_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.

Official reference index

Capability Documentation
listCatalogCategories listCatalogCategories
searchCatalogItems searchCatalogItems
getCatalogItem getCatalogItem

Prerequisites

  1. Depends on linkfox-amazon-store-auth；python scripts/check_auth_dependency.py，exit 42 requires installing the authorization skill first.
  2. The application must have the Catalog Items related role;searchCatalogItems when retrieving by identifiers+SKU , the query must include sellerId(the script automatically uses the input parameter identifiersType=SKU when sellerId）。

Current Capabilities

Capability path Script
listCatalogCategories catalog/v0/categories list_catalog_categories.py
searchCatalogItems catalog/{2022-04-01|2020-12-01}/items search_catalog_items.py
getCatalogItem catalog/{version}/items/{asin} get_catalog_item.py

Default Catalog Items version:2022-04-01; input parameter catalogItemsVersion can be changed to 2020-12-01。

Shared modules:_spapi_catalog_common.py。

Quick Parameters

  • listCatalogCategories：marketplaceId + asin or sellerSku(choose one).
  • searchCatalogItems：marketplaceIds + keywords or identifiers + identifiersType(mutually exclusive); optional includedData、brandNames、classificationIds、pageSize、pageToken。
  • getCatalogItem：asin、marketplaceIds; optional includedData、locale。

Scripts

export LINKFOXAGENT_API_KEY="<your-key>"

python scripts/list_catalog_categories.py '{"sellerId":"A1...","region":"NA","marketplaceId":"ATVPDKIKX0DER","asin":"B08N5WRWNW"}'

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

python scripts/get_catalog_item.py '{"sellerId":"A1...","region":"NA","asin":"B08N5WRWNW","marketplaceIds":["ATVPDKIKX0DER"],"includedData":["summaries","images"]}'

Display Rules

  1. First look at developerProxy.errcode / httpStatus, then read categories / catalogItems / catalogItem。
  2. listCatalogCategories Use v0 to query the key MarketplaceId(singular), unlike the search/get marketplaceIds .
  3. The gateway path whitelist must include catalog/v0/ and catalog/2022-04-01/(or 2020-12-01）。

Important Limitations

  • This skill reads the Amazon product catalog (Catalog), not seller orders; for orders see linkfox-amazon-store-orders。
  • includedData, and returned fields follow the Amazon schema; see references/api.md。

Amazon SP-API interface protection and retry guidelines

When the same store consecutively receives 400, 403, 404, or 429 from Amazon SP-API, the gateway returns 450, 453, 454, or 459 with a brief cooldown. These custom status codes are not native Amazon statuses and do not indicate account suspension; the purpose is to avoid continued anomalies or high-frequency calls expanding 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 this 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, the store/site it belongs to, 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, and do not bypass protection by switching scripts or repeatedly creating tasks; prioritize following retryAfter、blockedUntil, and if unavailable, follow the durations described in the table.
  • For 450/453/454, you must first correct the parameters, authorization, or resource identifier, and after the cooldown retry cautiously at most once; if triggered again, stop calling. During 453, stop all SP-API calls for that store.
  • Keep existing task IDs such as reportId、feedId ; when the result of a write operation is uncertain, query the status first rather than replaying it directly.
  • Explain store protection to the user first, then give the reason, handling, and wait time. You may reply: "To protect the security of your Amazon store, it has been detected that Amazon SP-API consecutively returned {reason}, and it has currently entered brief protection. Please first {handling action}, and try again after an estimated {wait 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： skillName：linkfox-amazon-store-catalog。

More cross-border skills:LinkFox Skills