This Skill covers the 45 operations of Amazon Fulfillment Inbound v2024-03-20 , as well as the 6 v0 query/document operations that still need to be used in conjunction with the new process. All requests continue to use the production chain of the Amazon Store series:POST /spApi/developerProxy, and the server resolves authorization through sellerId + region .
Prerequisites (must read first)
- This Skill depends on
linkfox-amazon-store-auth. First runpython scripts/check_auth_dependency.py; if the exit code is42and stderr containsDEPENDENCY_MISSING:, first install or load that dependency. - Select a store through the auth Skill, obtain
sellerIdandregion。regiononly allowsNA、EU、FE。 - does not receive, store, or pass through
amzAccessToken、accessToken、refreshToken. Do not let the caller override Amazonpath、methodor gatewayqueryString。 - First read the grouped documentation matching the task; for the complete contract entry point, see references/api.md。
Invocation method
- API endpoint：
POST /spApi/developerProxy(for complete parameters/responses/error codes, seereferences/api.md） - Python script：
python scripts/<operation_script>.py '<JSON 参数>' [--inline] [--no-cache] - Invocation constraints: This tool follows the unified free configuration of the Amazon Store Skill; by default, the same parameter combination in the same session is called only once, and the script has a 24h local cache. On failure/empty results, do not automatically change parameters, paginate, or continuously probe; if further calls are needed, obtain user consent first.
Output strategy (default script behavior)：
- Alwayswrite the complete response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-fulfillment-inbound-<timestamp>.json（<cwd>is the working directory when the script is executed,<session>taken from the environment variableSESSION_ID; writing to/tmpis 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, maximum list field length, and the first 3 samples)
- Add
--inlineto force full printing to stdout (also written to disk) - Add
--no-cacheto force this read/generate operation to access the gateway; use only when the user requests a refresh or external state changes have been confirmed
Data reading suggestions: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer to use jq or ConvertFrom-Json to extract on demand from the saved JSON file, avoiding putting the entire JSON into the context.
Working method
Each public script represents only one fixed operation, and a single execution calls the gateway at most once. The unified executor is responsible for:
- validating common fields, path/query/body, enums, pagination limits, and key nested constraints;
- percent-encoding path segments and query parameters;
- mapping the v0 CLI's lowerCamelCase parameters to the PascalCase wire names required by Amazon;
- recognizing 200/201/202/204 success responses and parsing JSON;
- returning an explicit
nextActionfor asynchronous responses, but not automatically polling; - saving the complete response, and for large responses displaying only a summary on stdout.
Invocation format:
python scripts/<operation_script>.py '<JSON parameters>' [--inline] [--no-cache]
Common parameters:
| Parameter | Required | Description |
|---|---|---|
sellerId |
Yes | Authorized Seller ID |
region |
Yes | NA / EU / FE |
| path/query parameter | Conditional | Use the lowerCamelCase name from each operation documentation |
requestBody |
Conditional | Amazon JSON body; explicitly passing this object is recommended, and placing body fields at the top level is also supported |
confirmWrite |
Required for submit-type operations | Pass a boolean after the user explicitly confirms the target and selection true; if this value is missing for the 8 deterministic submit operations, the script will refuse before the gateway call |
skipDepCheck |
No | For local debugging only |
Example:
python scripts/get_inbound_plan.py '{"sellerId":"A1...","region":"NA","inboundPlanId":"wf12345678-1234-1234-1234-123456789012"}'
python scripts/create_inbound_plan.py '{"sellerId":"A1...","region":"NA","requestBody":{"destinationMarketplaces":["ATVPDKIKX0DER"],"items":[{"labelOwner":"AMAZON","msku":"SKU-1","prepOwner":"SELLER","quantity":10}],"sourceAddress":{"name":"Warehouse","addressLine1":"1 Main St","city":"Seattle","countryCode":"US","phoneNumber":"+1-206-555-0100","postalCode":"98101","stateOrProvinceCode":"WA"}}}'
python scripts/get_labels.py '{"sellerId":"A1...","region":"NA","shipmentConfirmationId":"FBA...","pageType":"PackageLabel_Letter_2","labelType":"UNIQUE"}'
Select operation
| Group | Purpose | Detailed parameters and script |
|---|---|---|
| Inbound Plans | Create, read, cancel, rename, view plan contents | inbound-plans.md |
| Packing | Generate/confirm packing plan, submit box specifications, view packing groups | packing.md |
| Placement | Generate, list, confirm placement plans | placement.md |
| Shipments | Read shipment, boxes/items/pallets, names and addresses, tracking | shipments.md |
| Content Updates | Preview and confirm changes to existing shipment contents | shipment-content-updates.md |
| Delivery | Delivery window and delivery challan | delivery-windows-and-documents.md |
| Self-Ship | India self-delivery appointment slots and appointments | self-ship-appointments.md |
| Transportation | Generate, compare, confirm transportation plans | transportation.md |
| Prep / Compliance / Labels | Prep, compliance, and product labels | prep-compliance-labels.md |
| Async Status | Query operationId execution status |
asynchronous-operations.md |
| Retained v0 | Prep instructions, box labels, BOL, legacy shipment query | legacy-v0.md |
Execution rules
- First confirm the current workflow stage and existing IDs; for the source of IDs and cross-version mapping, see references/identifiers.md. When a plan/shipment already exists, prefer read-only recovery and do not recreate it.
- Before write operations, confirm the user's intent and target store. The following 8 deterministic submit operations must show the key selections to the user and obtain explicit confirmation before execution:
cancelInboundPlan、confirmPackingOption、confirmPlacementOption、confirmShipmentContentUpdatePreview、confirmDeliveryWindowOptions、cancelSelfShipAppointment、scheduleSelfShipAppointment、confirmTransportationOptions。 confirmTransportationOptionsmay accept shipping fees; before confirmation, display each shipment's option, fee, currency, transit time, and expiration. Do not choose paid items on the user's behalf by default.- The 19 asynchronous initiation operations return
operationIdand then only callget_inbound_operation_status.pyto query.IN_PROGRESSstop and tell the user to check again later;FAILEDdisplayoperationProblems, and do not proceed to downstream write steps; onlySUCCESSmay continue. - The script layer does not automatically paginate, poll, try different parameters, or replay POST/PUT. The existing gateway only refreshes the token and transparently retries once when it recognizes token expiration; when results are uncertain due to 429/500/503 or timeout, prefer recovering state through status/read operations.
updateInboundPlanName、updateShipmentNameThe 204 empty body of is success and is not treated as a parsing failure.getLabels/getBillOfLadingmust usegetShipmentreturned byshipmentConfirmationId; the script also accepts this alias. Download URLs may expire quickly, so download immediately after obtaining them and do not store URLs long-term.
For the complete standard path, Pack Later, India, own carrier, and shipment content update workflows, see references/workflows.md. For marketplace restrictions, see references/marketplace-constraints.md。
Output and error handling
- The complete response is saved to
linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-fulfillment-inbound-<timestamp>.json; stdout prints the actual path. - Print the complete JSON when the response is no more than 8 KB; print a summary when larger;
--inlineforce printing the complete JSON. - Always first determine
developerProxy.errcode, then determinehttpStatus, and finally read the operation result field. - For 401/402, API Key, authorization, computing power, or balance issues, handle according to references/onboarding.md .
- When Amazon returns 400/403/404/409/413/415/422, after correcting the input or process state, the user decides whether to call again.
Reference routing
- Fields, responses, pagination, error semantics: read references/api.md。
- Business process selection: read references/workflows.md。
- ID generation and v2024/v0 mapping: read references/identifiers.md。
- Country/marketplace differences: read references/marketplace-constraints.md。
- For a certain operation's method/path/body/script: only read the corresponding
references/apis/*.mdgrouped documentation.
For problem feedback, use skillName: linkfox-amazon-store-fulfillment-inbound, and attach the desensitized operation, associated ID, and developerProxy response.
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 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, 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 calls for that store, 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 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 changing scripts or repeatedly creating tasks; prioritize following
retryAfter、blockedUntil, and when there is none, follow the durations described in the table. - For 450/453/454, you must first correct parameters, authorization, or resource identifiers, 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 cause, handling, and waiting 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 {handling action}, and try again after an estimated {waiting time}; this does not indicate account suspension, nor is it a package or computing power limit.” Do not only say “LinkFox rate limiting” or “server busy”.
Computing power consumption rules
No computing power is consumed (subject to the gateway's actual billing).
More cross-border Skills:LinkFox Skills