Connect Amazon data to your AI agent

What makes Amazon data for AI agents usable?

An AI agent needs Amazon data that is joined, documented and scoped to the accounts it may read. Without that, it guesses field names and mixes up periods. Commerce Spine gives agents 10 query-ready entities with 316 documented columns, so the agent works from a data dictionary instead of memory. [site]

Start with one question you can check by hand. For example: which campaigns spent the most in the last 30 days? A named account and a clear date range make the first answer easy to verify against the returned rows. [cs]

How do you connect Amazon data to an AI agent?

There are two ways in, and both reach the same data. Claude Desktop and the Claude Code CLI use the official Commerce Spine plugin: install it once, sign in once, then ask questions in plain English. Sign-in uses a local browser callback, so a browser-only Claude cannot complete it. [connect]

Codex, Cursor, custom agents and plain scripts call the API directly with a scoped token. Every call goes to a single /graphql route, and the reference documents 39 operations and 10 entities. If your setup can make an HTTPS request, it can query the warehouse. The data API guide walks through the request shape. [cs] [site]

Keep the token out of shared prompts, article drafts and public repositories. The plugin stores its credentials in a local file restricted to your user account and never prints or logs the token. [connect]

Which Amazon data can the agent see?

The entities cover account, product, campaign, keyword, search term, product target and advertised product performance, plus current state, inventory and listings. The accountPerformance entity alone returns 16 fields, from adSpend and adRevenue to orderedRevenue and totalProductSales. The account performance guide shows that query end to end. [cs]

Before an agent builds a query, it can discover what exists. amazonAccounts lists the accounts inside your permission scope. dataCatalog and dataAsset return each asset's fields and whether they can be filtered, grouped, sorted or aggregated. That makes it easy to tell a real field from one the model invented. [cs]

dataFreshness returns the latest available report date per asset. Ask for it first, then pick the period. New accounts get 30 days backfilled at the first sync, and the warehouse keeps syncing from there. [cs] [site]

How do permissions and logging work?

Protected operations take an agent token in the Authorization header. The API applies the intersection of your organization's scope and the user's scope. Ask for an account outside it and the response is a FORBIDDEN_ACCOUNT_SCOPE error. A missing or invalid token returns UNAUTHENTICATED. [cs]

Access is limited to the people you invite through team roles and the scoped tokens you issue. Every request is logged with the token that made it, and you can revoke any token instantly. So you can hand one agent its own token, see what it asked for, and cut it off without touching anyone else. [site]

How do you check an agent's answer?

Every reporting response carries rows, totals, pageInfo and queryInfo. queryInfo includes a requestId, the effective account IDs, the date range and the number of rows returned. Ask your agent to quote those next to its conclusion, so you can match the answer to the request that produced it. [cs]

Check pageInfo too. When hasNextPage is true, the agent should send the returned endCursor as after and keep reading. A ranking built from the first page alone is incomplete. [cs]

One query covers at most 90 days on a paid plan and 30 days on Free. A longer range returns DATE_RANGE_TOO_LARGE, and the documented fix is to split the period into smaller windows. ACOS and ROAS come back already calculated in totals.derived, so the agent does not have to rebuild them from spend and revenue. [cs] [site]

Why not point the agent at raw Amazon reports?

Amazon spreads seller data over separate APIs, each with its own auth, shapes, quirks and rate limits. Commerce Spine joins six Amazon sources into one warehouse, so an agent can compare this week with last quarter without pulling reports again. [site]

Raw reports also change under you. According to Amazon's Reports API documentation, Amazon periodically adds new fields and field values to reports, so any parser you build has to cope with that. The SP-API comparison covers what a direct integration takes. [amazon]

There is also paperwork you cannot code around. Most of the deeper Amazon data sits behind an application that Amazon has to approve on its marketplace. Commerce Spine already carries that approval, so you authorize your accounts through Amazon and skip the application entirely. [site]

What should your first prompt say?

Give the agent a question, an account and a period, then tell it how to show its work. A prompt that holds up well: "Use amazonAccounts to confirm the account, check dataFreshness, then rank campaigns by adSpend for the last 30 days. Show the account, period, fields and requestId you used, and say whether more pages remain." [cs]

That one instruction covers most first-week mistakes. The agent confirms scope before it reads, picks a period the data actually covers, and ranks on spend instead of a similar revenue field. Once those answers trace cleanly back to the response, widen the workflow to more accounts or a scheduled script. [cs]

What do the four analysis skills add?

Data alone gives an agent numbers. Four analysis skills come inside the subscription so it reads them like someone who runs accounts. PPC Semantic Analyst turns a metrics dump into root-caused, prioritized insights. Ads Query Orchestrator plans multi-step pulls across tables so the agent does not reinvent the joins each session. [site]

Profit-First PPC Analyst ranks recommendations by profit impact, using real fee and cost data from the warehouse. Amazon Ads Entities maps the Ads hierarchy from portfolio to target and links it to what it spends against. Your agent proposes; you decide what to change and where. See pricing to start free on one connected account. [site]

Sources

1. Commerce Spine: official API reference
2. Commerce Spine: connect Claude setup guide
3. Commerce Spine: product overview and FAQ
4. Amazon: Reports API documentation