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

linkfox-amazon-store-orders

General & other

View repository

Updated 10-16 06:23

About this skill

Amazon Store Orders

This skill and linkfox-amazon-store-auth、linkfox-amazon-store-report、linkfox-amazon-store-listings、linkfox-amazon-store-pricing 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, and the server parses the token (do not pass amzAccessToken, unless for compatibility with legacy calls). Forward upstream GET / POST / PATCH。

How to call

  • API endpoint：POST /spApi/developerProxy(different SP-API operations are distinguished by path/method; 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 constraints: this tool consumes compute; on failure/empty results, do not automatically switch keywords, paginate, or repeatedly probe; if further retrieval is needed, 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/linkfox-amazon-store-orders-<timestamp>.json（<cwd> is the working directory when the script runs, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_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 --inline to force full printing to stdout (also written to disk)

Data reading suggestions: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer to use jqorConvertFrom-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 problem resolution:

Abnormal situations

  • API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and 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 a similar meaning.

Official reference index

Capability Documentation
searchOrders searchOrders
getOrder (v2026-01-01) getOrder
getOrderBuyerInfo (deprecated) getOrderBuyerInfo
getOrderAddress (deprecated) getOrderAddress
getOrderItems (deprecated) getOrderItems
getOrderItemsBuyerInfo (deprecated) getOrderItemsBuyerInfo
updateShipmentStatus updateShipmentStatus
getOrderRegulatedInfo getOrderRegulatedInfo
updateVerificationStatus updateVerificationStatus
confirmShipment confirmShipment

Prerequisites (must read first)

This skill depends on linkfox-amazon-store-auth。

  1. Run python scripts/check_auth_dependency.py; if exit code 42 and stderr contains DEPENDENCY_MISSING:, please first install linkfox-amazon-store-auth。
  2. Do notbypass the dependency within this skill to implement authorization or token logic.

Current Capabilities (script overview)

Capability developerProxy path(key points) Script
searchOrders orders/2026-01-01/orders + Query search_orders.py
getOrder orders/2026-01-01/orders/{orderId} + Query get_order.py
getOrderBuyerInfo orders/v0/orders/{orderId}/buyerInfo get_order_buyer_info.py
getOrderAddress orders/v0/orders/{orderId}/address get_order_address.py
getOrderItems orders/v0/orders/{orderId}/orderItems + NextToken get_order_items.py
getOrderItemsBuyerInfo orders/v0/orders/{orderId}/orderItems/buyerInfo get_order_items_buyer_info.py
updateShipmentStatus orders/v0/orders/{orderId}/shipment，POST JSON update_shipment_status.py
getOrderRegulatedInfo orders/v0/orders/{orderId}/regulatedInfo get_order_regulated_info.py
updateVerificationStatus orders/v0/orders/{orderId}/regulatedInfo，PATCH JSON update_verification_status.py
confirmShipment orders/v0/orders/{orderId}/shipmentConfirmation，POST JSON confirm_shipment.py

Shared logic see scripts/_spapi_orders_common.py(for import only by scripts in the same directory, not a standalone CLI).

Quick Parameters (summary)

  • searchOrders：createdAfter 或 lastUpdatedAfter(choose one);marketplaceIds; optional fulfillmentStatuses、fulfilledBy、maxResultsPerPage、paginationToken(previous page nextToken）、includedData。
  • getOrder：orderId; optional includedData(such as BUYER, FULFILLMENT, PACKAGES).
  • getOrderItems / getOrderItemsBuyerInfo: optional nextToken → query parameter NextToken。
  • updateShipmentStatus：marketplaceId、shipmentStatus(ReadyForPickup / PickedUp / RefusedPickup); optional orderItems。
  • updateVerificationStatus: pass regulatedOrderVerificationStatus object, or the full package requestBody。
  • confirmShipment：requestBody as the complete object required by the official specification (usually including packageDetail , etc.).

Scripts

export LINKFOXAGENT_API_KEY="<your-key>"

python scripts/search_orders.py '{"sellerId":"A1...","region":"NA","marketplaceIds":["ATVPDKIKX0DER"],"lastUpdatedAfter":"2026-05-01T00:00:00Z"}'

python scripts/get_order.py '{"sellerId":"A1...","region":"NA","orderId":"123-1234567-1234567","includedData":["FULFILLMENT","PACKAGES"]}'

Display Rules

  1. First check the gateway developerProxy.errcode / httpStatus, then parse the additional fields appended by each script (such as searchOrders、order）。
  2. POST/PATCH script:stdout contains requestBody(the assembled Amazon request body), which facilitates troubleshooting.
  3. v0 buyer/address/line item The interface is documented officially as deprecated; for new integrations, prefer v2026-01-01 's searchOrders / getOrder and includedData to align business fields.
  4. searchOrders The default rate is relatively low (officially about 0.0056 req/s), note 429。
  5. Restricted PII / RDT is subject to Amazon's data protection policy; see references/api.md。

Important Limitations

  • Permissions:Orders and related roles; some reads may require Restricted Data Token, which is not implemented in this skill.
  • Path Allowlist: if the gateway returns 1005 or other refused forwarding, the backend must allow the orders/v0/... and orders/2026-01-01/... prefixes.
  • The response structure follows the Amazon schema; see references/api.md。

Amazon SP-API Interface Protection and Retry Guidelines

When the same store continuously receives 400, 403, 404, or 429 from the 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 expanding store risk due to persistent anomalies or high-frequency calls.

Status and message Scope Trigger and Cooldown Handling
450：400，请求异常，请优化您的参数 Store + endpoint More than 3 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 20 minutes Stop retrying with the original parameters, check required fields, marketplace, ID, date, and request body
453：403，店铺未授权，请先授权 All store endpoints More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Stop calls for that store; check authorization, permissions, store ownership, and region
454：404，资源不存在，请优化您的参数 Store + endpoint 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 endpoint path
459：429限流中，请降低频率 Store + endpoint 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 progressively
  • Immediately stop automatic or concurrent retries; do not bypass protection by switching scripts or repeatedly creating tasks; preferentially follow retryAfter、blockedUntil; when unavailable, follow the durations in the table.
  • For 450/453/454, you must first correct the parameters, authorization, or resource identifiers, then after cooldown retry cautiously at most once; if triggered again, stop calling. During 453, stop all SP-API calls for that store.
  • Preserve existing reportId、feedId and other task IDs; when the result of a write operation is uncertain, query the status first rather than replaying it directly.
  • First explain store protection to the user, then give the reason, the action to take, and the wait time. You may reply: "To protect the security of your Amazon store, it has been detected that Amazon SP-API continuously returned {reason}, and a brief protection period is currently in effect. Please first {action}, and try again after an estimated {wait time}; this does not mean the account is banned, 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，skillName：linkfox-amazon-store-orders。

More cross-border skills:LinkFox Skills