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

linkfox-amazon-store-report

Design & creation

View repository

Updated 10-15 20:04

About this skill

Amazon Store Report Retrieval

This skill provides end-to-end automated retrieval of Amazon Seller Central reports: request → poll → download → decompress → preview. Supports 95+ report types (inventory / orders / sales / financial / FBA / returns / Brand Analytics, etc.).

⚠️ Prerequisites — MUST READ FIRST

This skill depends on linkfox-amazon-store-auth(authorization and store/token management).

🛑 If linkfox-amazon-store-auth is not installed / not loaded, please install it first, then return to this skill.

How to determine whether linkfox-amazon-store-auth is available

Before executing any report task, the agent mustfirst perform a dependency check:

  1. Read any of the following paths(the skill loading path depends on the runtime environment;scripts/check_auth_dependency.py will automatically detect using the same rules):
    • Repository / common flat directory:<skills_dir>/linkfox-amazon-store-auth/SKILL.md
    • Claude：~/.claude/skills/linkfox-amazon-store-auth/SKILL.md
    • Cursor：~/.cursor/skills/...、~/.cursor/skills-cursor/...
    • OpenClaw：<OPENCLAW_WORKSPACE>/skills/...、~/.openclaw/skills/...、~/.agents/skills/...(consistent with the common paths in the OpenClaw Skills documentation )
    • Hermes Agent：~/.hermes/skills/<category>/linkfox-amazon-store-auth/SKILL.md, as well as ~/.hermes/plugins/<plugin>/skills/linkfox-amazon-store-auth/SKILL.md(consistent with the layout in the Hermes Skills documentation )
  2. Or run the script directly：python scripts/check_auth_dependency.py, the script will exit with exit code 42 when missing, and output a structured prompt to stderr (starting with DEPENDENCY_MISSING: ). The script has built-in OpenClaw / Hermes path detection; if config.yaml is configured in Hermes's skills.external_dirs, please set the environment variable HERMES_SKILLS_EXTERNAL_DIRS(use the system path separator to concatenate multiple directories) for detection.
  3. If the above checksall fail, then it is determined that linkfox-amazon-store-auth is not installed。

Standard handling when not installed is detected

When it is detected that linkfox-amazon-store-auth is not installed, the agent mustexecute in the following order:

  1. Attempt automatic installation(preferred):
    • If the current runtime has skill installation tools (e.g., skill marketplace / skill management MCP / install_skill type tools),immediately callto install linkfox-amazon-store-auth。
    • After successful installation, reload and execute this skill from the beginning.
  2. Guide the user to install manually(fallback):
    • Explain to the user: "This skill depends on linkfox-amazon-store-auth, which is not yet installed. Please go to LinkFox Skills to install this skill, and let me know once the installation is complete; I will continue pulling reports for you."
    • Do notbypass the dependency and directly call /spApi/authorizeUrl、/spApi/storeTokens、/spApi/authorizedStores and other interfaces—the store selection and token flows of these interfaces are the responsibility of linkfox-amazon-store-auth ; this skill is only responsible for the report business itself.
  3. Must not silently degrade: if neither automatic installation nor user confirmation is obtained, muststop executionand report the fact that dependencies are missing to the user; do not attempt alternatives on your own.

Collaboration approach after dependencies are satisfied

  • This skill depends on auth for store selection (sellerId+region), and directly executes the report lifecycle via /spApi/developerProxy (the server parses the token).
  • Authorization, the prerequisite store selection for authorization, token refresh, and other operations—are delegated to linkfox-amazon-store-auth; this skill does not duplicate these tasks.

Core Concepts

  • Report Type: Amazon official report type enum, for example GET_MERCHANT_LISTINGS_ALL_DATA、GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL. For the complete list, see references/report-types.md。
  • Marketplace ID: specific site ID within the region, for example US = ATVPDKIKX0DER。
  • Report lifecycle: request report → poll processingStatus（IN_QUEUE / IN_PROGRESS / DONE / FATAL / CANCELLED）→ DONE then get reportDocumentId → get download URL → download (mostly gzip TSV) → decompress.
  • Rate limits: Reports API is about 0.0222 req/s; polling must preserve an interval (default 30s).

Data Fields

Report Request Input

Field Type Required Description
sellerId string Yes Authorized Amazon Seller ID
region string Yes NA / EU / FE
reportType string Yes Report type enum value
marketplaceIds array Yes List of target marketplace IDs
dataStartTime string No ISO 8601, report start time
dataEndTime string No ISO 8601, report end time
lastUpdatedDate string No Required for some Vendor reports, see references/report-requests/ corresponding md
reportOptions object No such as Brand Analytics' reportPeriod、asin/asins; sales traffic's dateGranularity/asinGranularity , etc.Each reportType description：references/report-requests/types/<REPORT_TYPE>.md(index types/README.md); for those with a JSON Schema, see also report-requests/README.md
pollInterval int No Polling interval in seconds (default 30)
maxAttempts int No Maximum number of polls (default 20)

Report Output

Field Type Description
reportId string Report request ID
reportDocumentId string Report document ID
downloadPath string Local downloadedabsolute path(already decompressed, including filename)
fileName string Saved filename (consistent with the last segment of downloadPath )
localFileUri string Local file:// URI, convenient for clients to open the local file
extractedFileHttpUrl string Local temporary HTTP direct link, used for downloading in the browserDecompressedfile (default serveExtractedFileHttp enabled)
extractedFileHttpServeSeconds int Duration to keep the local HTTP service running (default 300, minimum 10)
extractedFileHttpNote string Indicates that the link is local-only and valid for a limited time
amazonDownloadUrl string (Optional) appears only when includeAmazonSourceUrl: true : Amazon source address, generally a compressed package, usually does not need to be given to end users
compressionAlgorithm string Include it if the API returns a compression algorithm (such as GZIP)
tempDirectory string Temporary directory
fileSize int File size (bytes)

How to call

  • API endpoint：POST /spApi/developerProxy(different operations are distinguished by 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 below)
  • Cost constraint: This tool consumes compute; on failure/empty results, do not automatically switch keywords, paginate, or repeatedly probe; if retrieval needs to continue, 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 variable SESSION_IDautomatically aggregated by user task;Writing to /tmp is prohibited, report an error if the current directory is not writable)
  • 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 sample entries)
  • add --inline to force full printing to stdout (also written to disk)

Data reading recommendations: first look at the summary to judge whether it is sufficient; when specific fields are needed, preferentially use jqorConvertFrom-JsonorConvertFrom-Json to extract on demand from the saved json file, avoiding putting the entire JSON into context.

Available Scripts

  • scripts/get_report.py ⭐ — End-to-end automated report retrieval (recommended）
  • scripts/check_auth_dependency.py — proactively detect whether dependency skill linkfox-amazon-store-auth is installed

resolve authentication and compute resource issues

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

Abnormal situations

  • API Key not configured: the environment variable LINKFOX_AGENT_API_KEYis not configured, nor is LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute resources or balance: the message contains "insufficient compute resource balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

Usage Scenarios

Scenario 0: Dependency Check (MUST run first)

This step must be run first every time this skill is entered.

  1. Try to read linkfox-amazon-store-auth/SKILL.md(if the tool allows)
  2. or execute: 
    python scripts/check_auth_dependency.py
  3. If the exit code is non-zero or stderr contains DEPENDENCY_MISSING:, handle according to the above "standard handling when not installed is found" process
  4. After dependencies are satisfied, proceed to the normal business scenario

Scenario 1: Pull Amazon Report (Automated, Recommended)

User request: "I want to pull the inventory report"/"get the order report"/"download the sales traffic report", etc.

Steps：

  1. Dependency check（Scenario 0）
  2. Pre-select store: delegate to linkfox-amazon-store-auth
    • to call /spApi/authorizedStores to let the user select a store, and determine sellerId + region
    • Do notfirst call /spApi/storeTokens to get the raw token; the script directly passes through developerProxy to pass the selector
  3. Identify report type: match according to the user's request reportType
    • Inventory:GET_MERCHANT_LISTINGS_ALL_DATA、GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA
    • Orders:GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL
    • Sales traffic:GET_SALES_AND_TRAFFIC_REPORT
    • Finance:GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE
    • Complete list:references/report-types.md
  4. Execute script： 
    python scripts/get_report.py '{
  "sellerId": "A1EC6SZ7XAMURH",
  "region": "NA",
  "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
  "marketplaceIds": ["ATVPDKIKX0DER"]
}'
  5. The script will automatically: use sellerId+region to call developerProxy(server-side token parsing) → request report → poll → download → decompress → preview → output JSON;After completionin stderr and JSON provide local absolute path（downloadPath）、local machine file URI（localFileUri), and by default start a short-lived local HTTP service, generating extractedFileHttpUrl(used to download inthe same machine's browserdecompressedfiles). When showing to the user, at least provide extractedFileHttpUrl、downloadPath and fileName; the script, in serveSeconds after the timer ends, will close the service, and the link will immediately become invalid. If an Amazon source address (mostly a compressed package) is needed, set only during debugging includeAmazonSourceUrl: true。

Scenario 2: Manual Report Flow (Advanced)

For scenarios requiring fine-grained control, you can, through /spApi/developerProxy Manual-driven:

  1. Fetch an existing report(faster): 
    path: reports/2021-06-30/reports
method: GET
queryString: reportTypes=<type>&marketplaceIds=<ids>
  2. Create a new report： 
    path: reports/2021-06-30/reports
method: POST
body: {"reportType": "...", "marketplaceIds": [...]}
  3. Check status： 
    path: reports/2021-06-30/reports/{reportId}
method: GET
  4. Fetch download link： 
    path: reports/2021-06-30/documents/{reportDocumentId}
method: GET

Scenario 3: Custom Date Range / Polling

python scripts/get_report.py '{
  "sellerId": "A1EC6SZ7XAMURH",
  "region": "NA",
  "reportType": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
  "marketplaceIds": ["ATVPDKIKX0DER"],
  "dataStartTime": "2024-01-01T00:00:00Z",
  "dataEndTime": "2024-01-31T23:59:59Z",
  "pollInterval": 15,
  "maxAttempts": 40
}'

Marketplace IDs by Region

Region Country Marketplace ID
NA United States ATVPDKIKX0DER
NA Canada A2EUQ1WTGCTBG2
NA Mexico A1AM78C64UM0Y8
EU United Kingdom A1F83G8C2ARO7P
EU Germany A1PA6795UKMFR9
FE Japan A1VC38T7YXB528

For more marketplace IDs, see references/report-types.md。

Display Rules

  1. Dependencies before business: before the dependency check passes,must notstart any report-related calls.
  2. Present data only: show report retrieval progress, download path, preview of the first few lines; do not perform business interpretation.
  3. Respect the report type chosen by the user: if the user specifies a report type, pull only that type; do not switch to other types without authorization.
  4. Clear errors: when a report fails (FATAL / 403, etc.), explain the reason and hand the decision back to the user.
  5. Security: do not output/do not pass raw token; business only depends on sellerId+region。
  6. After completion, show the address and local download link: after the script ends successfully, you must tell the user extractedFileHttpUrl(local HTTP download of the extracted file, time-limited),downloadPath(local absolute path),fileName(file name), and localFileUri ; and state that it is "only available on the same computer running the script, within the service retention time." Do not use the Amazon source URL as the user download entry by default; use it only when the user explicitly requests it or troubleshooting requires it. includeAmazonSourceUrl。

CRITICAL: Report Failure Handling Rules

  • NEVER automatically try alternative report types when user's specified report fails.
  • When a report request fails (FATAL, 403, etc.),immediately stop and tell the user the fact of the failure。
  • do notdecide on the user's behalf to pull another report type.
  • Explain the failure reason clearly and let the user decide the next step (retry / change type / check permissions, etc.).
  • Example:GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT when it fails,do notautomatically switch to pulling GET_MERCHANT_LISTINGS_ALL_DATA。

Common Report Failure Reasons

  • 403 Unauthorized: missing API permissions or not enrolled in Amazon Brand Registry
  • FATAL: this store does not support this report type or there is insufficient data
  • Brand Analytics reports require brand registry
  • Vendor reports are limited to Vendor accounts

Important Limitations

  • Depends on linkfox-amazon-store-auth: if not installed, it must be installed first; see Prerequisites.
  • Token expiration: the server-side token expires in about 1 hour;developerProxy can, by sellerId+region , automatically parse/renew. When expired, you can also retry after the auth skill's refreshToken .
  • Rate limits: Reports API 0.0222 req/s; the default 30s polling interval is a safe interval.
  • Report timeliness: some financial reports may take 10–30 minutes; increase as needed maxAttempts。
  • Path allowlist: the backend sp-api.developer-proxy.allowed-path-prefixes must allow reports/2021-06-30/reports。

User Expression & Scenario Quick Reference

Applicable — report retrieval scenarios:

User Says Scenario
"pull Amazon inventory report" / "pull inventory report" Scenario 1
"download order data" / "download orders report" Scenario 1
"get sales and traffic report" / "sales and traffic report" Scenario 1
"pull financial settlement report" / "settlement report" Scenario 1
"check FBA inventory" / "FBA inventory report" Scenario 1
"pull the order report for a certain period" / "orders from 2024-01-01 to ..." Scenario 3

Not applicable — beyond this skill:

  • Authorize a new store, list authorized stores, refresh/query token → please use linkfox-amazon-store-auth
  • Product listing management, order processing, and ad delivery → handled by other skills

Boundary judgment：

  • This skill is only responsible for "dependency check + report retrieval business",Authorization/token belongs to the dependency skill。
  • Any call entering this skill must first run Scenario 0.

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 interfaces of the store More than 2 times within 60 seconds: 5 minutes; more than 4 times within 10 minutes: 30 minutes Stop calls 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, and 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, parameters, authorization, or resource identifiers must first be corrected, 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、feedId and 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, 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 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：

When any of the following situations occurs, automatically call the Feedback API to report:

  1. This skill's functional description does not match actual behavior
  2. The result does not match the user's intent
  3. The user expressed dissatisfaction or appreciation
  4. Other points you think can be improved

Follow references/api.md to call the Feedback API according to the specification in it, and do not interrupt the user's main process.

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.