SETUP GUIDE

Connect Claude to Commerce Spine

The Commerce Spine plugin gives Claude secure, read-only access to your Amazon data through the Commerce Spine Data Layer. Install it once, sign in once, then ask questions in plain English.

EARLY ACCESS The plugin surface below may change.

Before you start

Two things need to be true before the sign-in will work.

A Commerce Spine account

With permission to create an API token and at least one linked Amazon account. Your onboarding contact can confirm this.

Claude running on your computer

Claude Desktop or the Claude Code CLI. Sign-in uses a temporary local callback, so a browser-only Claude cannot complete it.

Read-only accessEverything runs on your machine. The plugin talks to exactly two endpoints: the console at https://console.commercespine.com for sign-in, and https://api.commercespine.com/graphql for data. It cannot change anything in your account.

CLAUDE DESKTOP

Install in Claude Desktop

Follow these steps in the Claude Desktop app.

At the top of the left sidebar, select Code mode.
Click Customize at the top of the left sidebar.
In the modal that opens, click Plugins in the left-hand list. You may need to scroll down to see it.
At the top right, click Add → Add Marketplace → Add from a repository.
Paste this repository name and click sync:
Repository
```
WeBuildAgents/commercespine-claude-plugin
```
If the connection does not work with the repository name, use the full URL instead: https://github.com/WeBuildAgents/commercespine-claude-plugin
Click + next to Commerce Spine to add it. The plugin is now installed, so continue to Sign in.

CLAUDE CODE

Install in Claude Code

Run these two commands inside any Claude Code session. The first registers the marketplace, and the second installs the plugin from it.

Claude Code

# 1. Register the marketplace
/plugin marketplace add WeBuildAgents/commercespine-claude-plugin

# 2. Install the plugin
/plugin install commercespine@commercespine-marketplace

If /commercespine:login does not appear in the / menu right away, reload and check again:

Claude Code

/reload-plugins

Updating laterRun /plugin update commercespine to pick up new versions. You do not need to sign in again after an update.

AUTHENTICATION

Sign in

Open a new chat and run:

Claude Desktop or Claude Code

/commercespine:login

Here is what happens next:

Your browser opens to the Commerce Spine sign-in page.
You sign in and create a new API token. Existing tokens cannot be shown again after they are created, so this step always mints a fresh one.
You confirm, and the browser tab shows “Connected to Commerce Spine” with a note that you can close the tab and return to Claude.
Claude reports that the connection succeeded and was verified.

Browser did not open?The login step prints a URL. Copy it into your browser manually and continue from there. The rest of the flow is identical.

Your token is saved locally at ~/.config/commercespine/credentials.json, restricted to your user account. It is never printed, logged, or sent anywhere except the Commerce Spine API.

CONNECTION CHECK

Verify the connection

Right after a successful sign-in, Claude offers to list the Amazon accounts your token can reach. Say yes. It is the quickest end-to-end proof that everything works, and it shows you exactly which stores are in scope.

At any time afterwards, ask Claude to check your connection status:

Command

Run commercespine-config to check my Commerce Spine connection.

That reports the endpoints in use and whether a token is present. It never prints the token itself.

START QUERYING

Ask your first question

Just ask normally. When a question is about your Amazon advertising or retail data, Claude picks up the commercespine:data-layer skill and answers it by querying your account.

Example prompts

Which keywords drove my ACOS change last month?

Show me my top 10 ASINs by ad spend in June.

Compare campaign performance week over week.

To force the data layer explicitly rather than letting Claude decide:

Claude Desktop or Claude Code

/commercespine:data-layer [your question]

Safe by designAll queries are read-only. The plugin refuses anything that would write to or change your data.

SUPPORT

Troubleshooting

The most common issues and what to do about them.

Symptom	Likely cause	What to do
`/commercespine:login` is not in the menu	The plugin is not enabled in this chat or scope	Re-check the install steps, run `/reload-plugins`, then start a new chat
The browser never opened	Sign-in could not launch a browser on your system	Copy the URL that was printed and paste it into your browser manually
“Login timed out after 10m0s”	Sign-in was not completed inside the time window	Run `/commercespine:login` again and complete the browser steps
“State mismatch” in the browser	The callback did not match the request that started it	Close the tab and run `/commercespine:login` again. Never reuse an old connect link
“Could not start local callback server”	A VPN, firewall, or locked-down network is blocking the local port	Allow local connections to `127.0.0.1`, then retry
“The token was saved but could not be verified” / “The token was saved but Commerce Spine rejected it”	The token was stored, but the API rejected it or was unreachable	Check your network connection, then run `/commercespine:login` again
Data questions suddenly fail with an auth error	The token was suspended or revoked in the console	Run `/commercespine:login` to reconnect with a new token

Still stuck? Reply to your onboarding email and the team will take a look.