Partner API

Build against your MixShift data and your connected Amazon accounts: warehouse analytics, Amazon SP-API, and the Amazon Ads API, behind one OAuth 2.0 gateway. early access

Getting access

There are two paths in, depending on whose data your code touches.

Building on your own MixShift account? You do not need to register an application. A tenant admin creates a service credential at /admin ("Create with raw secret"): you get a client_id and client_secret on the spot (the secret is shown once, at creation, so store it in your secret manager as you mint it). Exchange it for a bearer token with the client_credentials grant at POST /oauth/token and start calling. Credentials are read-only by default (ads:write is grantable at mint time), revocable and rotatable at any time, and built for unattended use: schedulers, sync pipelines, CI, and multi-user apps that serve your own team. This is the right path for almost every current MixShift customer. (Setting up the MixShift Claude plugin for unattended runs rather than your own code? Use the admin console's primary setup code flow instead: a one-time code the plugin exchanges itself, so no human ever handles the secret.)

Building a product that other MixShift tenants sign into? Then you need a registered partner application so each tenant can authorize you on a consent screen. Email support@mixshift.io with your app name, redirect URIs, and the scopes you need; you receive a client_id (and a secret for confidential clients) and use the authorization-code flow with PKCE below.

Coming from legacy direct MySQL access (IP allowlist + database credentials)? The service credential replaces that setup. The same SQL runs through POST /api/query, so nothing about your workflow changes except the connection. You drop the IP dependency (any host works, and no allowlist updates when your network changes), your server never holds a database password, and compromise recovery is instant: revoke the credential and any stolen access token expires within the hour.

OAuth 2.0

GET /oauth/authorize — authorization-code flow with PKCE. Tenants sign in and consent.
POST /oauth/token — exchange codes, refresh tokens, or mint machine tokens via client_credentials.
POST /oauth/revoke — revoke a refresh token when a user disconnects (RFC 7009).
Discovery: /.well-known/oauth-authorization-server.

Send the access token as Authorization: Bearer <token> on every call.

Scopes

Scope	Grants
`account:read`	Account and merchant metadata.
`retail:read`	The Amazon SP-API surfaces: on-demand reports, pricing, and the operation catalog (orders, inventory, catalog, finances, Data Kiosk).
`ads:read`	The Amazon Ads API surfaces: profiles, reporting v3, exports, entity lists, budget usage, recommendations.
`brand_analytics:read`	Brand Analytics data (rides the retail surface today).
`ads:write`	Audited Ads mutations: bids, budgets, states, negatives, campaign creation. Opt-in per credential: tenant admins can grant it when creating a service credential at `/admin`; partner applications get it case by case from MixShift. Every write defaults to a dry-run preview and is audit-logged.

Raw-SQL warehouse access (POST /api/query) requires the full read set; see Warehouse SQL below.

Surfaces

Endpoint	Scope	What it does
`GET /api/amazon/merchants`	retail:read	Merchants you can act for (one row per account + marketplace).
`POST /api/amazon/reports` + poll/document	retail:read	On-demand SP-API reports; documents return as short-lived presigned URLs.
`/api/amazon/pricing/*`	retail:read	Featured Offer Expected Price + Competitive Summary batches.
`GET /api/amazon/spapi/operations` `POST /api/amazon/spapi/call`	retail:read	Catalog-driven SP-API operations: orders, FBA inventory, catalog items, fees, finances, Data Kiosk. The operations listing documents every call.
`GET /api/amazon/ads/profiles` `GET /api/amazon/ads/operations` `POST /api/amazon/ads/call`	ads:read (+ ads:write for writes)	Catalog-driven Amazon Ads operations: reporting v3, exports, entity lists, budget usage, recommendations, and audited writes.

Partner data plane: /v1

The /v1 endpoints are the contract-stable partner surface: snake_case params, cursor pagination, explicit currency on money fields, and date windows anchored to the latest fully complete Amazon data day. Domain errors use { "error": { "code", "message" } } with a small stable code vocabulary (account_required, account_not_found, validation_error, rate_limited, ...).

Endpoint	Scope	What it does
`GET /v1/me`	account:read	Who this token is: tenant id, person label, granted scopes.
`GET /v1/accounts`	account:read	Every account/brand the tenant exposes, with per-domain auth status (retail, ads) and currency. Pass an account's `id` as `account_id` on data endpoints.
`GET /v1/ads/account-summary` `GET /v1/ads/account-pacing` `GET /v1/ads/campaign-performance` `GET /v1/ads/search-terms` `GET /v1/ads/asin-performance`	ads:read	Windowed ads performance: account rollups, MTD pacing, and per-campaign / search-term / ASIN aggregates with cursor pagination.
`GET /v1/retail/sales` `GET /v1/retail/traffic`	retail:read	Daily retail series (sales, orders, units, sessions, page views) with window totals.
`GET /v1/brand-analytics/search-query-performance`	brand_analytics:read	Search Query Performance aggregated by query (weekly grain). Domains without data return `200` with an `availability` block.

Warehouse SQL: `/api/query`

Read your warehouse directly with SQL when the /v1 endpoints do not cover what you need. Your credential resolves server-side to your own tenant database (the standard MixShift schema) over a read-only connection, so a query only ever sees your own data.

Endpoint	Scope	What it does
`POST /api/query`	full read set	Run read-only SQL. Body `{ sql, params?, queryTimeoutMs? }`; `params` is a positional array (`?` placeholders) or a named object. Returns `{ ok: true, rows, rowCount, durationMs }` or `{ ok: false, kind, friendly }`.
`GET /api/tables`	full read set	List the tables in your database.
`GET /api/table/<name>`	full read set	Columns for one table (a `SHOW COLUMNS` result).

Raw SQL spans every data domain, so this surface needs the full read set (account:read, ads:read, retail:read, brand_analytics:read), which is the default for a read-only credential. Per-call limits: queryTimeoutMs defaults to 60s and caps at 120s; a response caps at 50,000 rows (too_many_rows) and 10 MB (response_too_large), so paginate large extracts with LIMIT / OFFSET or chunk by date. Raw SQL couples you to the warehouse schema; prefer /v1 when you want a versioned contract.

Write safety model

Write operations default to a dry run: the call validates, snapshots current state, logs an audit row, and returns a preview without touching Amazon.
Only an explicit "dryRun": false commits. Show your user the preview first.
Commits are capped at 200 items per call and audit-logged with the pre-write snapshot.

Errors and limits

Failures share one envelope: { "ok": false, "kind": "...", "friendly": "..." }. Branch on kind (insufficient_scope, reauth_required, throttled, merchant_not_found, ...), not HTTP status.

Rate limit: 240 requests/minute per credential (HTTP 429 + Retry-After when exceeded).
Access tokens are short-lived; refresh via POST /oauth/token.
Amazon-side throttles surface as kind: "throttled"; back off and retry.

Questions: support@mixshift.io · mcp.mixshift.io