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

linkfox-amazon-store-external-fulfillment

Office & productivity

View repository

Updated 10-16 17:24

About this skill

Amazon store External Fulfillment

This skill and linkfox-amazon-store-auth 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 / PUT / PATCH。

Applicable channels: Seller Flex / FBA Onsite, Multi Seller Flex, Easy Ship, Self Ship, MFN Self Delivery, Amazon Pharmacy, etc. (subject to the merchant allowlist and role).

How to call

  • API endpoint：POST /spApi/developerProxy(for full parameters/responses see references/api.md）
  • Python script：python scripts/<脚本名>.py '<JSON 参数>' [--inline]
  • Cost constraint: this tool consumes compute; on failure/empty results do not automatically paginate or repeatedly probe; if you need to continue, first explain to the user that additional consumption will be incurred.

Output strategy (default script behavior)：

  • Alwayswrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-external-fulfillment-<timestamp>.json
  • Response body ≤ 8 KB: after writing to disk, print the full JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs only a summary
  • Add --inline to force full printing (also written to disk)

Data reading suggestion: look at the summary first; when specific fields are needed, use jq / ConvertFrom-Json to extract from the file written to disk.

Resolve authentication and compute issues

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

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 a similar meaning.

Official reference index

Module Capability Documentation
Inventory batchInventory batchInventory
Shipping getShipments getShipments
Shipping getShipment getShipment
Shipping processShipment processShipment
Shipping createPackages createPackages
Shipping updatePackage updatePackage
Shipping updatePackageStatus updatePackageStatus
Shipping retrieveShippingOptions retrieveShippingOptions
Shipping generateInvoice generateInvoice
Shipping retrieveInvoice retrieveInvoice
Shipping generateShipLabels generateShipLabels
Returns listReturns listReturns
Returns getReturn getReturn

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.
  3. The merchant needs External Fulfillment allowlist, and the application needs the Direct-to-Consumer Shipping (Restricted) role.

Current Capabilities (script overview)

Capability developerProxy path(key points) Script
batchInventory externalFulfillment/inventory/2024-09-11/inventories，POST post_batch_inventory.py
getShipments externalFulfillment/2024-09-11/shipments + Query get_shipments.py
getShipment .../shipments/{shipmentId} get_shipment.py
processShipment .../shipments/{shipmentId}?operation=，POST process_shipment.py
createPackages .../shipments/{shipmentId}/packages，POST create_packages.py
updatePackage .../shipments/{shipmentId}/packages/{packageId}，PUT update_package.py
updatePackageStatus Same path as above, PATCH update_package_status.py
retrieveShippingOptions .../shipments/{shipmentId}/shippingOptions + packageId retrieve_shipping_options.py
generateInvoice .../shipments/{shipmentId}/invoice，POST generate_invoice.py
retrieveInvoice Same path as above, GET retrieve_invoice.py
generateShipLabels .../shipments/{shipmentId}/shipLabels?operation=，PUT generate_ship_labels.py
listReturns externalFulfillment/2024-09-11/returns + Query list_returns.py
getReturn .../returns/{returnId} get_return.py

Shared logic see scripts/_spapi_ef_common.py(for import by scripts in the same directory only).

Quick Parameters (summary)

  • batchInventory：requests 1 to 10 items. Simplified items:action=fetch|update、locationId、skuId; update requires quantity. MFN single warehouse commonly uses locationId=DEFAULT; Seller Flex uses a 4-digit warehouse code. Advanced:useAmazonRequestShape:true directly pass the official requests。
  • getShipments: required status(e.g. ACCEPTED/CREATED); optional locationId、marketplaceId、channelName、lastUpdatedAfter/Before、maxResults、paginationToken。
  • processShipment：operation=CONFIRM|REJECT; when REJECT, you can pass referenceId/lineItems or requestBody。
  • createPackages / updatePackage: package dimensions and weight and packageLineItems are placed in packages or requestBody。
  • updatePackageStatus: mainly used for Self Delivery; pass status/subStatus/reason。
  • generateShipLabels：operation=GENERATE|REGENERATE; optional shippingOptionId、packageIds。
  • listReturns: optional status(new returns commonly use CREATED）、returnLocationId, time window,nextToken。

Typical fulfillment flow:getShipments → processShipment(CONFIRM) → createPackages → retrieveShippingOptions → generateInvoice → generateShipLabels →（Self Delivery）updatePackageStatus。

Scripts

export LINKFOXAGENT_API_KEY="<your-key>"

python scripts/post_batch_inventory.py '{"sellerId":"A1...","region":"NA","requests":[{"action":"fetch","locationId":"DEFAULT","skuId":"SKU-1","marketplaceAttributes":{"marketplaceId":"ATVPDKIKX0DER","channelName":"MFN"}}]}'

python scripts/get_shipments.py '{"sellerId":"A1...","region":"NA","status":"ACCEPTED","locationId":"ABCD"}'

python scripts/process_shipment.py '{"sellerId":"A1...","region":"NA","shipmentId":"...","operation":"CONFIRM"}'

Display Rules

  1. First check the gateway developerProxy.errcode / httpStatus, then parse the script's additional fields (such as batchInventory、shipments、invoice）。
  2. batchInventory on success is often 207 Multi-Status; check item by item responses[].status。
  3. most write operations succeeding may be 204(no body); stdout will mark success: true。
  4. Invoice/shipping label documents are mostly Base64 or presigned URLs; do not repeatedly paste entire large base64 blobs into the context.
  5. Path allowlist: if it returns 1005, the backend needs to allow the externalFulfillment/ prefix.

Important Limitations

  • Permissions:Direct-to-Consumer Shipping (Restricted); merchants need allowlist.
  • Writing inventory is an absolute-value publish, not incremental; only sync SKUs that have changed; special characters in SKUs need URL encoding (the script already handles simplified input parameters).
  • And linkfox-amazon-store-orders(regular Orders),linkfox-amazon-store-feeds(Feed inventory update),linkfox-amazon-store-report(inventory report) have different boundaries; do not mix them up.
  • On Seller Flex, retrieveShippingOptions often returns empty; Easy Ship on most global marketplaces may not support generateInvoice(except India).
  • The return 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 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 interfaces of the store More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Stop calling this 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 the resource ID, owning store/marketplace, 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 task IDs such as reportId、feedId ; 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 provide the reason, handling, and waiting time. You may reply: "To protect your Amazon store security, it has been detected that Amazon SP-API continuously returned {reason}; it has currently entered a brief protection period. Please first {handling action}, and try again after an estimated {waiting time}; this does not mean 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 (subject to actual gateway billing; if the gateway bills, handle according to computing power rules).

Feedback： See references/api.md，skillName：linkfox-amazon-store-external-fulfillment。

More cross-border skills:LinkFox Skills