Amazon SP-API connector: a private app for your own seller account

This page is for sellers and their IT staff who want OrgRelay to read orders, FBA stock and listings from Amazon Seller Central. It walks through developer registration, the self-authorized refresh token, regions and marketplaces, and the two listing changes that wait for approval.

The connector uses the Selling Partner API with Login with Amazon (LWA) tokens. It exchanges your refresh token for an access token and sends it in the x-amz-access-token header. AWS SigV4 signing is not used; Amazon dropped that requirement in October 2023. The app is a private one, authorized only for your own account. You do not publish it in the Appstore. For OrgRelay's general connector model, see the connector spec.

#What staff can ask

• "How many Unshipped orders do we have on the US store since Monday?" This calls orders.search with status: Unshipped and date_from. If no date is given, the connector looks back 30 days.
• "What was in order 113-4567890-1234567?" This calls orders.get, which fetches the order and its items in parallel.
• "How much FBA stock is sellable, inbound and reserved for SKU MUG-01 in Germany?" This calls inventory.list with the German marketplace_id.
• "What were units and sales for October on amazon.co.uk?" This calls reports.sales_summary.
• "Drop SKU MUG-01 to 14.99 USD." This calls products.update_price and waits for approval.

These names come from the shared vocabulary in standard tools. The same orders.search question therefore works against the Shopify connector or the Lingxing ERP connector, which many Amazon sellers already use.

#Tools

Things the code does that you should know:

• Paging uses Amazon's tokens. For orders, once a cursor (Amazon's NextToken) is passed, Amazon ignores the other filters. The marketplace is still sent, because Amazon requires it.
• products.search has no keyword filter. It pages through all listings, at most 20 per page.
• inventory.list pages within Amazon's pages. Amazon returns FBA summaries in fixed pages and does not accept a page size. The connector's cursor records both Amazon's page token and a position inside that page, so a small limit walks through a page in steps before moving to Amazon's next one.
• inventory.set_stock sets a quantity. The value replaces what Amazon has; it is not added to or subtracted from it. It writes the DEFAULT fulfilment channel, which is merchant-fulfilled stock. Amazon controls FBA quantities, so this tool cannot change them. This tool requires OrgRelay 1.4.0 or later.
• The sales period uses UTC midnight. date_from and date_to are sent as UTC midnight, and the end date is excluded. For October, use 2026-10-01 to 2026-11-01.

#Credentials, roles and regions

The connection form asks for:

• LWA client ID, which looks like amzn1.application-oa2-client.…
• LWA client secret
• Refresh token, from self-authorization. It starts with Atzr|.
• Seller ID, the merchant token from Seller Central account info. The Listings Items calls need it in the path.
• Region: na (North America and Brazil), eu (Europe, Middle East and India) or fe (Japan, Singapore, Australia). This picks the sellingpartnerapi-na/eu/fe.amazon.com host.
• Default marketplace ID, optional. If you leave it blank, OrgRelay picks the first marketplace the account participates in when you connect. The connection then shows the store name and every participating country code.

Two advanced fields exist for the static sandbox and for a different LWA token URL. Leave them empty for a live account.

Roles. Request Product Listing, Pricing, Inventory and Order Tracking, and Selling Partner Insights during developer registration. Amazon's role mappings show that getOrders and getOrderItems accept Inventory and Order Tracking among other roles. Listings Items accepts Product Listing or Inventory and Order Tracking. The FBA inventory summary accepts Amazon Fulfillment or Product Listing. You do not need restricted roles such as Direct-to-Consumer Shipping, because the connector never reads buyer PII.

Token lifetimes. The access token lasts about an hour. The connector caches it and requests a new one 60 seconds before it expires. Amazon describes the refresh token as long-lived, and generating a new one does not cancel older ones. The client secret is different. Amazon makes you rotate LWA credentials every 180 days, and the old secret stops working seven days after you create a new one. Put a reminder in the calendar of whoever owns Seller Central. OrgRelay stores all three secrets encrypted and shows only the last four characters; the auth page has the details.

#Which actions need approval

Both write tools go through a Listings Items PATCH and both create an approval request. The approver sees the arguments as they will be sent:

• Price change: SKU, new price, currency and marketplace. The connector replaces purchasable_offer with our_price as value_with_tax. Check that the figure matches how prices are shown in that marketplace, especially in the EU where prices include VAT.
• Quantity change (inventory.set_stock): SKU, the new merchant-fulfilled quantity and marketplace. The approver should read the number as the final stock level, not as a change.

If product_type is left out, the connector sends PRODUCT. Amazon validates the patch. Any issue with severity ERROR, or a status of INVALID, comes back as a failure and nothing is applied. A successful call returns a submissionId, and Amazon takes a few minutes to show the change on the listing. Each approved call carries the idempotency key orgrelay-approval-<approval id>. The Listings Items API has no idempotency header, so the connector does not send the key to Amazon. See approvals and writes for how approvers are chosen, and human in the loop for why every write stops for a person.

#Set it up

1. Sign in to Seller Central as the primary user. Amazon only lets the primary user self-authorize. Open Apps and Services → Develop Apps.
2. Complete developer registration as a private developer building for your own business. Request the roles listed above and wait for approval. Amazon reviews private apps too, which can take days or longer.
3. Add a new app client with API type SP API. Copy the LWA client ID and client secret.
4. Click Authorize app next to the app. Amazon's self-authorization guide explains this step; the app can stay in draft. Copy the refresh token, which is shown once.
5. Find your merchant token under Settings → Account Info.
6. In OrgRelay, open Admin → Business systems → App directory, pick Amazon Seller, fill in the fields and click Connect. OrgRelay calls marketplaceParticipations to check the token.
7. Grant the connector to roles. The security model explains how grants and tool switches are enforced. A typical split gives buyers and planners the read tools and keeps the two write tools for a pricing lead.

#Limits and things it does not do

SP-API rate limits are per operation and per seller. The one most people hit is getOrders, with a default of 0.0167 requests per second and a burst of 20, as listed on Amazon's Orders API rate limit page. Other operations have their own figures, and Amazon reports the live value in the x-amzn-RateLimit-Limit header. When Amazon returns 429, OrgRelay waits for Retry-After, or 60 seconds if it is absent. OrgRelay's own guards apply as well: 120 calls per minute per connection, and a 60-second pause after three failures in a row.

orders.search and orders.get use the Orders API v0 operations getOrders, getOrder and getOrderItems. Amazon has published Orders API v2026-01-01 and lists these v0 operations for removal, with a migration deadline of 27 March 2027.

It does not:

• read buyer names, addresses, emails or tax data;
• create shipments, confirm shipping or buy labels;
• touch advertising (that is a separate API), A+ content, or FBA inbound plans;
• change FBA quantities, product titles, bullet points or images.

The sandbox only returns fixed sample responses. There is no test store where an order can be placed, so try write tools on one low-risk SKU first. If you write your own connector for another Amazon API, test it with the connector check before binding it. Results longer than about 12,000 characters are cut before the AI sees them. To react to changes as they happen rather than polling, see events.

#Official MCP server and OrgRelay

Amazon's amzn/selling-partner-api-samples repository includes sp-api-dev-mcp, published on npm as @amazon-sp-api-release/sp-api-dev-mcp. It holds a developer assistant (documentation search, endpoint catalogue, code samples, and a tool that can run live requests with your LWA credentials) and a workflow builder. The repository also has a Data Kiosk MCP server for sales and traffic queries. Amazon labels these as educational examples, not supported products, and advises a security review before production use.

If you want one of them inside OrgRelay, connect it as a third-party MCP connection. OrgRelay then puts its own layer around it, as it does for this connector: per-role access, an approval before every write, one audit log across Amazon, your ERP and your accounting system, all running on the company's own machine. See enterprise patterns and the list of official MCP servers. The business side is on OrgRelay for ecommerce.

Need an Amazon API this connector does not cover, such as Finances or Reports? Describe it in an OpenAPI file and use the OpenAPI import, or build a small server over the MCP transport from the code templates.

#Common questions

Do we need a restricted role to read orders?

No. The connector never asks for buyer names, addresses or phone numbers, so it needs no Restricted Data Token and no restricted role. Order lists and line items come back without buyer PII, which is what the connector returns.

Can one connection cover both our US and UK accounts?

No. A connection points at one regional endpoint (na, eu or fe). Marketplaces inside the same region can share it by passing marketplace_id, for example the UK and Germany under eu. Selling in both the US and the UK therefore needs two connections, one per region. Whether both can use the same refresh token depends on how the accounts are linked in Seller Central, so authorize each region and check.

What happens when the LWA client secret is rotated?

Amazon requires a new client secret every 180 days. After you generate one, the old secret keeps working for seven days. Paste the new secret into the existing OrgRelay connection. The refresh token does not change, so there is nothing to re-authorize.

#Related

• All connectors
• Lingxing ERP connector
• Xero connector for settlements in the books
• Security model
• Connector check