How a Read-Only Amazon Data API Works

How does the Amazon data API work?

Commerce Spine's read-only Amazon data API lets your agent query seller data through one endpoint. A bearer token controls which accounts it can read. [cs]

Commerce Spine's API is a read-only data layer built for agents, scripts, and automations rather than for a browser dashboard. The entire collection runs through a single endpoint, POST {{baseUrl}}/graphql, and behavior depends on which operation is sent in the request body. [cs]

Access uses a bearer token in the Authorization header rather than a browser session. The docs are explicit that console session tokens belong to a separate surface and must not be used for this API. A public health check operation is available without a token, so a caller can confirm the service is up before authenticating. [cs]

How do you find the accounts you can query?

Before running a data query, a caller can list the Amazon accounts within its organization and user permission scope, then use the returned id as the accountId in later queries. A catalog operation lists the available assets and their fields, and a freshness operation returns the latest available date across assets or for a specific asset. [cs]

The queryable entities

The documented collection lists nine queryable entities: accountPerformance, productPerformance, campaignPerformance, keywordPerformance, searchTermPerformance, productTargetPerformance, advertisedProductPerformance, inventory, and listing. Most of these accept a date range as input; inventory and listing are the exceptions and instead return the latest pinned snapshot per account. [cs]

accountPerformance rolls up daily account-level advertising, revenue, and order metrics. productPerformance breaks the same kind of data down by product and SKU, including average rating and review count. campaignPerformance, keywordPerformance, searchTermPerformance, productTargetPerformance, and advertisedProductPerformance each report advertising results at a different level, from campaign status and daily budget down to individual search terms and advertised ASINs. [cs]

inventory returns a current stock snapshot per account, with optional nested detail drawn from the Manage FBA and Restock reports. listing returns a current All Listings Report snapshot, with an optional item-detail nest for fields such as description and feature bullet count. Both entities pin the latest report date per account instead of accepting a date range, so a freshness check on that specific asset is how a caller finds out how current the snapshot is. [cs]

Filtering, sorting, and pagination

Queries can combine where filters, orderBy sorting, and pagination in a single request. The documented example filters campaignPerformance to a campaign type and a minimum spend, sorts by spend descending, and pages the results. Pagination uses a first page-size parameter and an opaque after cursor taken from the previous response's endCursor. Omitting accountIds automatically scopes the query to the complete set of accounts the caller is authorized to see. [cs]

What are the query limits?

Two limits are built into the query engine and surface as specific error codes: a date range longer than 90 days returns DATE_RANGE_TOO_LARGE, and requesting an account outside the caller's scope returns FORBIDDEN_ACCOUNT_SCOPE. A request without a valid bearer token returns UNAUTHENTICATED. Handling these means splitting a long period into smaller windows and only using account IDs already returned by the accounts operation. [cs]

What this replaces: requesting reports directly from Amazon

Amazon's own Reports API is a request-and-retrieve system: a caller requests a report, then retrieves it once processing is complete, and can separately set up a schedule for recurring report requests. Amazon's documented use cases for this API are requesting a report, scheduling and retrieving reports, retrieving automatically generated reports, verifying that report processing is complete, and retrieving a report once it is ready. [amazon]

Access to the Reports API's operations, such as creating a report, retrieving a report or its document, and managing a report schedule, is gated by Amazon's role system: an application needs at least one of a defined set of roles, for example Inventory and Order Tracking, Pricing, or Finance and Accounting, to call these operations. That gating applies to the operations themselves, not to individual report types. [amazon]

Where an agent fits in

Because the API is read-only and returns structured rows, totals, and pagination metadata rather than raw report files, a coding agent or automation can query it directly instead of parsing a downloaded report. The docs describe this as a surface built for agents and automations, reachable by pointing any HTTP client with a bearer token at the single graphql endpoint. [cs]

What does the Free plan allow?

The Free plan connects 1 Amazon account. It allows 20 requests per hour and 40 requests per day. These limits apply per organization. [product]

Every plan backfills 30 days at first sync. The Free plan has a 30-day query window; paid plans allow 90 days per query. See the published plan limits. Inventory and listing queries still use their latest snapshots. [product] [cs]

Read the account performance guide for the next query. Use Amazon reporting data when checking the result. The inventory reports guide covers that data in more detail. [cs]

Sources

1. Commerce Spine official reference
2. Amazon Reports API documentation
3. Commerce Spine product and plan limits