Amazon Seller Central (SP-API)

This connector wraps Amazon's Selling Partner API (SP-API) — the official successor of MWS — using Login-with-Amazon (LWA) OAuth2. No AWS keys or SigV4 signing are needed (Amazon removed that requirement).

Setup (one-time, ~15 min + Amazon approval)

1. Register as a developer: Seller Central → Apps & Services → Develop Apps (you may first need to complete the developer profile in the Solution Provider Portal; Amazon reviews it manually, allow a few days).
2. Create a private app: Develop Apps → Add new app client → type Sellers → select the roles you need (e.g. "Inventory and Order Tracking", "Pricing", "Amazon Fulfillment", "Finance and Accounting", "Selling Partner Insights"). PII roles (buyer names/addresses) are restricted and NOT required for this connector.
3. Get LWA credentials: on the app row choose View → copy Client ID (amzn1.application-oa2-client.…) and Client Secret (amzn1.oa2-cs.v1.…).
4. Self-authorize: on the app row choose Authorize → Amazon shows the Refresh Token (Atzr|…). This token is long-lived; the connector exchanges it automatically for 1-hour access tokens (sent in the x-amz-access-token header — handled for you).
5. Fill the env vars:
   • SPAPI_CLIENT_ID, SPAPI_CLIENT_SECRET, SPAPI_REFRESH_TOKEN — from steps 3-4.
   • SPAPI_ENDPOINT — your region's API host:
     • Europe (DE/UK/IT/FR/ES/NL/SE/PL/TR/AE/IN/…): https://sellingpartnerapi-eu.amazon.com
     • North America (US/CA/MX/BR): https://sellingpartnerapi-na.amazon.com
     • Far East (JP/AU/SG): https://sellingpartnerapi-fe.amazon.com
   • SPAPI_MARKETPLACE_ID — the marketplace you sell in (call amazon_marketplace_ids for the full table; e.g. DE A1PA6795UKMFR9, US ATVPDKIKX0DER, IT APJ6JRA9NG5V4).
   • SPAPI_SELLER_ID — your merchant token (Seller Central → Account Info → Merchant Token). Only needed for amazon_get_listings_item; set any placeholder otherwise.

First call: run amazon_marketplace_participations — it needs no parameters and confirms auth + region are correct.

Sandbox

Set SPAPI_ENDPOINT to https://sandbox.sellingpartnerapi-eu.amazon.com (or -na/-fe) to hit the static sandbox: it returns canned responses when requests match predefined parameter patterns (e.g. Orders requires CreatedAfter=TEST_CASE_200). Same LWA credentials work; a draft app's refresh token may be sandbox-only (production returns 403 until the authorization is production-grade).

Marketplace scoping

All tools are pinned to SPAPI_MARKETPLACE_ID. To work across multiple marketplaces of the same region, create one connector per marketplace (cheap) — the underlying seller account and credentials can be identical.

What v1 deliberately does NOT do

• Buyer PII (names, shipping addresses, phone numbers): requires a Restricted Data Token and an Amazon-approved restricted role. Order data returned here is the non-PII view (IDs, status, totals, SKUs, quantities).
• Writes (price updates, listings edits, feeds): planned for a later version once the read workflows are proven.

Pagination & rate limits

List endpoints return a NextToken/pageToken — pass it back to fetch the next page. SP-API rate limits are per-endpoint (typically 0.0055–2 req/s with small bursts); on 429 the connector retries automatically with backoff, but space out heavy report loops.

Reports flow (3 steps)

1. amazon_create_report (e.g. reportType: "GET_FLAT_FILE_OPEN_LISTINGS_DATA") → returns reportId.
2. Poll amazon_get_report until processingStatus = DONE → gives reportDocumentId.
3. amazon_get_report_document → returns a pre-signed download url (valid ~5 min; document may be gzip). Fetch that URL yourself to read the content.