Amazon Store Report Retrieval

This skill provides end-to-end automated retrieval of reports from Amazon Seller Central: request → polling → download → decompression → preview. It supports over 95 report types (inventory / orders / sales / finance / 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 / loaded, please install it first before using this skill.

How to Check if

linkfox-amazon-store-auth

is Available

Before executing any report tasks, the agent must perform dependency checks first:

Read any of the following paths (skill loading path depends on the runtime environment;

scripts/check_auth_dependency.py

will automatically detect following the same rules):

Repository / general 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 common paths in OpenClaw Skills Documentation)

Hermes Agent:

~/.hermes/skills/<category>/linkfox-amazon-store-auth/SKILL.md

, and

~/.hermes/plugins/<plugin>/skills/linkfox-amazon-store-auth/SKILL.md

(consistent with the layout in Hermes Skills Documentation)

Or run the script directly:
```
python scripts/check_auth_dependency.py
```
, the script will exit with exit code
42
when the dependency is missing, and output structured prompts starting with
```
DEPENDENCY_MISSING:
```
to stderr. The script has built-in path judgment for OpenClaw / Hermes; if
```
skills.external_dirs
```
is configured in Hermes'
```
config.yaml
```
, please set the environment variable
```
HERMES_SKILLS_EXTERNAL_DIRS
```
(concatenate multiple directories with system path separators) for detection.
If all the above checks fail, it is determined that linkfox-amazon-store-auth
is not installed.

Standard Handling When Dependency Is Not Installed

When detecting that

linkfox-amazon-store-auth

is not installed, the agent must follow the steps below in order:

Attempt automatic installation (priority):
- If the current runtime has a skill installation tool (such as skill marketplace / skill management MCP /
```
install_skill
```
  -like tools), call it immediately to install
```
linkfox-amazon-store-auth
```
  .
- After successful installation, reload and execute this skill from the beginning.
Guide users to install manually (fallback):
- Explain to the user: "This skill depends on
```
linkfox-amazon-store-auth
```
  , which has not been installed yet. Please go to LinkFox Skills to install this skill, and let me know when it's done, I will continue to pull the report for you."
- Do not bypass the dependency to directly call interfaces like
```
/spApi/authorizeUrl
```
  ,
```
/spApi/storeTokens
```
  ,
```
/spApi/authorizedStores
```
  — the store selection and token processes for authorization are the responsibilities of
```
linkfox-amazon-store-auth
```
  , this skill only handles report-related business.
Do not silently degrade: If neither automatic installation nor user confirmation is available, stop execution and report the dependency missing fact to the user, do not attempt alternative solutions without permission.

Collaboration Method After Dependencies Are Met

This skill will internally call
```
/spApi/storeTokens
```
provided by the dependent skill to obtain
```
accessToken
```
, then execute the report lifecycle via
```
/spApi/developerProxy
```
.
Operations such as authorization, pre-authorization store selection, token refresh — handled by
linkfox-amazon-store-auth
; this skill does not repeat these tasks.

Core Concepts

Report Type: Official Amazon report type enumerations, such as

GET_MERCHANT_LISTINGS_ALL_DATA

GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL

. The complete list can be found in

references/report-types.md

Marketplace ID: Specific site ID within a region, e.g., US =
```
ATVPDKIKX0DER
```
.
Report lifecycle: Request report → poll
```
processingStatus
```
(
```
IN_QUEUE
```
/
```
IN_PROGRESS
```
/
```
DONE
```
/
```
FATAL
```
/
```
CANCELLED
```
) → get
```
reportDocumentId
```
when
```
DONE
```
→ retrieve download URL → download (mostly gzip TSV) → decompress.
Rate limits: Reports API is approximately 0.0222 req/s; polling intervals must be maintained (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 enumeration 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 corresponding md in `references/report-requests/`
reportOptions	object	No	Such as `reportPeriod` , `asin` / `asins` for Brand Analytics; `dateGranularity` / `asinGranularity` for sales and traffic reports, etc. Details for each `reportType` : `references/report-requests/types/<REPORT_TYPE>.md` (indexed in `types/README.md` ); for those with JSON Schema, see `report-requests/README.md`
pollInterval	int	No	Polling interval in seconds (default 30)
maxAttempts	int	No	Maximum number of polling attempts (default 20)

Report Output

Field	Type	Description
reportId	string	Report request ID
reportDocumentId	string	Report document ID
downloadPath	string	Absolute local path after download (decompressed, including file name)
fileName	string	Saved file name (consistent with the last segment of `downloadPath` )
localFileUri	string	Local `file://` URI, convenient for clients to open local files
extractedFileHttpUrl	string	Temporary local HTTP direct link for downloading the decompressed file in the browser (default `serveExtractedFileHttp` is enabled)
extractedFileHttpServeSeconds	int	Duration for keeping the local HTTP service running (default 300, minimum 10)
extractedFileHttpNote	string	Note that this link is only valid locally and within a limited time
amazonDownloadUrl	string	(Optional) Only appears when `includeAmazonSourceUrl: true` : Amazon source address, usually a compressed package, generally not necessary for end users
compressionAlgorithm	string	Included if the interface returns a compression algorithm (e.g., GZIP)
tempDirectory	string	Temporary directory
fileSize	int	File size (in bytes)

API Usage

This skill mainly calls

/spApi/developerProxy

(LinkFox Store Gateway Proxy) and reuses

/spApi/storeTokens

from

linkfox-amazon-store-auth

to obtain

accessToken

. For details, see

references/api.md

. Construct request body by
reportType
(including

reportOptions

, date rules): Full coverage page

references/report-requests/types/README.md

(one-to-one correspondence with each enumeration in

report-types.md

); for those with official JSON result Schema, see

references/report-requests/README.md

(GitHub schemas/reports).

Available Scripts

```
scripts/get_report.py
```
⭐ — End-to-end automated report retrieval (recommended)

scripts/check_auth_dependency.py

— Actively check if the dependent skill

linkfox-amazon-store-auth

is installed

Usage Scenarios

Scenario 0: Dependency Check (MUST run first)

Run this step every time you enter this skill.

Try to read
```
linkfox-amazon-store-auth/SKILL.md
```
(if allowed by the tool)
Or execute:
bash
```
python scripts/check_auth_dependency.py
```
If the exit code is non-zero or stderr contains
```
DEPENDENCY_MISSING:
```
, follow the process in "Standard Handling When Dependency Is Not Installed" above
Proceed to normal business scenarios only after dependencies are met

Scenario 1: Pull Amazon Report (Automated, Recommended)

User request: "I want to pull an inventory report" / "Get an order report" / "Download a sales and traffic report", etc.

Steps:

Dependency check (Scenario 0)
Pre-selection of store + token retrieval: Delegate to
```
linkfox-amazon-store-auth
```
- Call
```
/spApi/authorizedStores
```
  to let the user select a store
- Call
```
/spApi/storeTokens
```
  to obtain the token (this skill's script will automatically complete this step, no manual call needed)

Identify report type: Match

reportType

based on user's request

Inventory:

GET_MERCHANT_LISTINGS_ALL_DATA

GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA

Orders:

GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL

Sales and traffic:
```
GET_SALES_AND_TRAFFIC_REPORT
```
Finance:
```
GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE
```
Complete list:
```
references/report-types.md
```

Execute script:

bash

python scripts/get_report.py '{
  "sellerId": "A1EC6SZ7XAMURH",
  "region": "NA",
  "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
  "marketplaceIds": ["ATVPDKIKX0DER"]
}'

The script will automatically: retrieve token → request report → poll → download → decompress → preview → output JSON; upon completion, it will provide the local absolute path (
```
downloadPath
```
), local file URI (
```
localFileUri
```
) in stderr and JSON, and by default start a temporary local HTTP service to generate extractedFileHttpUrl
(for downloading the decompressed file in the browser on the same machine). When presenting to the user, at least show extractedFileHttpUrl
, downloadPath
and fileName
; the script will shut down the service after
```
serveSeconds
```
expires, and the link will become invalid immediately. To get the Amazon source URL (mostly compressed packages), set
```
includeAmazonSourceUrl: true
```
only during debugging.

Scenario 2: Manual Report Flow (Advanced)

For scenarios requiring fine-grained control, you can manually drive via

/spApi/developerProxy

Retrieve existing reports (faster):

path: reports/2021-06-30/reports
method: GET
queryString: reportTypes=<type>&marketplaceIds=<ids>

Create new report:

path: reports/2021-06-30/reports
method: POST
body: {"reportType": "...", "marketplaceIds": [...]}

Check status:

path: reports/2021-06-30/reports/{reportId}
method: GET

Retrieve download link:

path: reports/2021-06-30/documents/{reportDocumentId}
method: GET

Scenario 3: Custom Date Range / Polling

bash

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

Dependencies first, business later: Do not start any report-related calls until dependency check passes.
Only present data: Show report retrieval progress, download path, first few lines of preview; do not provide business interpretation.
Respect user-selected report type: Only pull the specified report type, do not switch to other types without permission.
Clear errors: When report retrieval fails (
```
FATAL
```
/ 403, etc.), explain the reason and return the decision-making power to the user.
Security: Mask accessToken in logs.
Show addresses and local download links after completion: After the script successfully ends, must inform the user of extractedFileHttpUrl
(temporary local HTTP download for decompressed files), downloadPath
(local absolute path), fileName
(file name) and localFileUri
; and explain that "it is only available on the same computer running the script and within the service retention period". Do not use the Amazon source URL as the default download entry for users; use
```
includeAmazonSourceUrl
```
only when explicitly requested by the user or for troubleshooting.

CRITICAL: Report Failure Handling Rules

NEVER automatically try alternative report types when user's specified report fails.
When report request fails (
```
FATAL
```
, 403, etc.), stop immediately and inform the user of the failure.
Do not decide on behalf of the user to pull other report types.
Clearly state the failure reason and let the user decide the next step (retry / change type / check permissions, etc.).

Example: When

GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT

fails, do not automatically 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 has insufficient data
Brand Analytics reports require brand registration
Vendor reports are only available for Vendor accounts

Important Limitations

Depends on
linkfox-amazon-store-auth
: Must install it first if not installed, see Prerequisites.
Token expiration:
```
accessToken
```
expires after 1 hour, the script automatically retrieves the latest token internally.
Rate limits: Reports API is 0.0222 req/s, default 30s polling interval is safe.
Report timeliness: Some financial reports may take 10–30 minutes, adjust
```
maxAttempts
```
as needed.

Path whitelist: 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 order report for a specific time period" / "orders from 2024-01-01 to ..."	Scenario 3

Not applicable — Beyond this skill:

Authorize new stores, list authorized stores, refresh/query tokens → Use
```
linkfox-amazon-store-auth
```
Product listing management, order processing, advertising delivery → Handled by other skills

Boundary judgment:

This skill only handles "dependency check + report retrieval business", authorization/token management belongs to the dependent skill.
Any call entering this skill must run Scenario 0 first.

Feedback:

Automatically call the Feedback API to report when any of the following occurs:

The skill's function description does not match the actual behavior
The result does not match the user's intent
The user expresses dissatisfaction or appreciation
Other areas you think can be improved

Call the Feedback API according to the specifications in

references/api.md

, do not interrupt the user's main process.

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

linkfox-amazon-store-report

NPX Install

Tags

SKILL.md Content (Chinese)