How Amazon Reporting Data Becomes Queryable in Commerce Spine

How does Amazon reporting data become queryable?

Commerce Spine turns Amazon reporting data into named entities that an agent can query through its read-only API. Performance queries return data for a chosen period. Inventory queries use the latest account snapshot. [cs]

Amazon's Selling Partner Reports API (v2021-06-30) is the current version sellers and vendors use to retrieve and manage reports, covering tasks such as monitoring inventory, tracking orders for fulfillment, getting tax information, and tracking returns. Working with it directly follows a documented sequence: request a report, optionally schedule recurring report requests, retrieve reports that are generated automatically, verify that report processing is complete, and then retrieve the finished report. [amazon]

Amazon also notes that it periodically adds new fields and field values to its reports, and that the format and structure of document identifiers may change over time, so any report parser built against this API needs to handle those updates. [amazon]

Which data can you query?

Commerce Spine's data layer puts a single read-only GraphQL endpoint (POST to /graphql) in front of Amazon reporting data, documented with 35 operations across 9 entities and a maximum demonstrated date range of 90 days. A public _health check works without a token; every other operation requires a bearer token in the Authorization header. [cs]

The nine documented entities are accountPerformance and productPerformance for daily account- and product-level results; campaignPerformance, keywordPerformance, searchTermPerformance, productTargetPerformance, and advertisedProductPerformance for advertising detail down to keyword, search term, target, and advertised product; and inventory and listing for current stock and catalog snapshots. Most of these accept a dateRange input and return rows with cursor-based pageInfo, optional aggregate totals, and request metadata in queryInfo. [cs]

How do inventory and listing snapshots work?

inventory and listing are the two exceptions to the dateRange pattern: each pins the latest available report_date per account rather than accepting a date window, and dataFreshness can be queried against the inventory or listing asset to read that pinned snapshot date. Selecting nested fields on inventory pulls in the Manage FBA and Restock report data, and selecting itemDetail on listing pulls in the item-detail report table, which is why the documentation recommends querying root fields only when checking how many bytes a request will process. [cs]

How much history can one query cover?

Because the maximum demonstrated range is 90 days, a query spanning a longer period returns a DATE_RANGE_TOO_LARGE error and needs to be split into smaller windows. Other documented errors include UNAUTHENTICATED for a missing or invalid token and FORBIDDEN_ACCOUNT_SCOPE for a requested account outside the caller's permitted scope; incorrect dataset permissions on the organization's side can also surface as underlying query-engine failures. Filtering (where), sorting (orderBy), and cursor pagination (first and after, with the cursor returned in pageInfo.endCursor) apply on top of these entities to narrow a query to what's needed. [cs]

Discovering what's available before querying

Before querying performance or inventory data, amazonAccounts lists which Amazon accounts, and their marketplace, currency, and connection details, fall within an organization and user's permission scope, and dataCatalog and dataAsset expose the field-level contract for a given asset, including which fields are filterable, groupable, sortable, or aggregatable. The account scope applied to any query is the intersection of the organization's and the requesting user's allowed accounts. [cs]

From report files to repeatable questions

Amazon's native Reports API is built around requesting, scheduling, and retrieving individual report files. Commerce Spine's layer normalizes that same reporting data into named entities that a single GraphQL query can return directly, with account scope, the date window, and pagination rules documented up front. That changes a repeatable operational question, such as pulling a given account's advertising and inventory figures for a defined window, from a multi-step report-request-and-download cycle into one documented query against a stable schema. [cs] [amazon]

Where to look next

The full entity list, field definitions, and worked query examples, including the quickstart, authentication, and error-handling reference, are in the Commerce Spine GraphQL API documentation. [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 Amazon data API guide for the next query. Use account performance 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