Amazon SP-API Integration
Connect your Amazon Selling Partner account with Login with Amazon (LWA), sync FBA inventory and orders, and ask the AI Assistant questions about stock levels, order volume, and revenue.
Overview
The Amazon Integration screen (Ecommerce → Marketplace Hub → Amazon) is the connection hub between TotalApp and your Amazon Selling Partner API (SP-API) account. It manages your LWA OAuth credentials, exchanges your refresh token for short-lived access tokens, fetches FBA inventory and recent orders, lists the exact SP-API endpoints in use, and provides an embedded AI Assistant with direct context of your marketplace data.
How SP-API Auth Works
Amazon SP-API is built from three components: LWA (Login with Amazon — Client ID & Secret authenticate your app), a per-seller Refresh Token (produced when a seller authorizes your app; stored AES-256 encrypted per tenant), and a Restricted Data Token (RDT) obtained on demand for endpoints that return customer PII. A legacy AWS IAM Role (SigV4) path is still supported for older apps but is no longer required.
Server-Side API Calls Only
All requests to the LWA token endpoint (api.amazon.com) and the regional SP-API endpoint (e.g. sellingpartnerapi-na.amazon.com) are made from the TotalApp server, never directly from your browser. Your Client Secret and Refresh Token are never exposed to the browser, and CORS restrictions are avoided.
Amazon SP-API Developer Setup & Onboarding Guide
Follow these four stages in order to obtain everything TotalApp needs. This is the practical checklist your developer team can work through end to end.
1Amazon Seller Central Developer Profile
- In Seller Central, go to Apps & Services → Develop Apps and register as a developer.
- Complete the Developer Profile: describe your app, the data you access, and your security & PII handling practices.
- Select the correct roles. If you fetch buyer name/address (Orders API), you must request PII (Personally Identifiable Information) roles — approval requires a clear data-use justification.
- Tip: keep the application description specific and honest about data flows. Vague or over-broad PII requests are the most common cause of rejection. Request only the roles you actually use.
2AWS Account & IAM Role Setup (legacy SigV4 only)
Required only if your app still uses the legacy SigV4 signing contract. Newer LWA-only apps can skip this.
- Create an IAM Policy granting
execute-api:Invokeon the SP-API ARN. - Create an IAM User (for the AssumeRole caller) and an IAM Role that will be assumed for signing.
- On the IAM Role, configure the Trust Relationship so the IAM User (or the SP-API service principal) is allowed to
sts:AssumeRole. - Record the Role ARN — enter it as the optional AWS Role ARN in TotalApp.
3LWA (Login with Amazon) App Registration
- In your app under Develop Apps, open the LWA credentials section.
- Generate/copy the Client ID and Client Secret.
- Configure the OAuth Redirect URI(s) that will receive the authorization code after a seller consents.
- Set the app to Draft for self-authorization, or publish it for third-party sellers.
4Auth Flow (OAuth 2.0 + optional AWS STS)
- The seller consents via the LWA authorization screen → Amazon redirects back with an Authorization Code.
- Exchange the code at
POST https://api.amazon.com/auth/o2/token(grant_type=authorization_code) for a Refresh Token. Store it AES-256 encrypted, keyed per tenant. - At call time, exchange the refresh token for a 1-hour Access Token (
grant_type=refresh_token). TotalApp caches this per tenant. - (Legacy) If SigV4 is required, call STS AssumeRole to get temporary AWS credentials and sign each request with SigV4. Otherwise, the access token in
x-amz-access-tokenis sufficient.
Setting Up the Connection in TotalApp
Open Settings → Integrations → Ecommerce → Amazon and enter:
| Field | Where to find it | Example |
|---|---|---|
| LWA Client ID | Seller Central → Develop Apps → LWA credentials | amzn1.application-oa2-client... |
| LWA Client Secret | Seller Central → Develop Apps → LWA credentials | amzn1.oa2-cs.v1... |
| Refresh Token | From the LWA authorization (consent) flow | Atzr|IwEBI... |
| Marketplace ID | Amazon marketplace you sell in | ATVPDKIKX0DER (US) |
| Region | NA / EU / FE, matching your marketplace group | na |
| AWS Role ARN (optional) | Only for legacy SigV4 apps | arn:aws:iam::…:role/SPAPIRole |
Back on the Amazon Integration screen, open the Seller Connection panel and click Test Connection. TotalApp performs an LWA token exchange (proving your OAuth credentials) and fetches a page of FBA inventory to confirm scope.
Connect Amazon Account button
The Connect Amazon Account button opens the Amazon consent screen to begin the LWA authorization flow. In production, the redirect callback exchanges the authorization code for the refresh token that is then saved (encrypted) for your tenant.
API Endpoints & Backend Modules
The screen exposes an API Endpoints reference panel. Path parameters such as {marketplaceId} are filled at call time. Endpoints returning customer PII are flagged RDT.
Authentication — api.amazon.com
| Method | Path | Purpose |
|---|---|---|
POST | /auth/o2/token | LWA access token exchange (refresh → access) |
POST | /tokens/2021-03-01/restrictedDataToken | Restricted Data Token (PII) |
Data APIs — sellingpartnerapi-<region>.amazon.com
| Method | Path | Module |
|---|---|---|
GET | /orders/v0/orders (RDT) | getOrders & getOrderItems |
GET | /fba/inventory/v1/summaries | getInventorySummaries |
POST | /feeds/2021-06-30/documents | submitFeed (price/inventory catalog) |
Rate Limits & Retry
SP-API uses a token bucket algorithm and returns HTTP 429 when you exceed the per-operation rate. TotalApp retries with jittered exponential back-off (up to 3 attempts) so transient throttling does not fail a sync.
Sync Settings & Logs
The Sync Settings panel exposes toggles for Auto Order Pull and Inventory Sync. The Sync Logs panel records each connection test, inventory sync, and order sync with a timestamp, scope, and success/failure detail so you can audit recent activity at a glance.
AI Assistant
The AI Assistant panel gives you a conversational interface into your Amazon data. When credentials are configured, TotalApp fetches your live FBA inventory and last-30-days orders server-side and provides them as context.
What You Can Ask
- Stock questions: “Which SKUs are out of stock or low on fulfillable inventory?”
- Order questions: “Summarize my orders from the last 30 days by status.”
- Revenue questions: “What is my total revenue and which products are top sellers?”
Writer Engine Support
The assistant respects your Settings → Agentic → Writer Engine choice. In Local CLI or Hosted API mode, live Amazon data is fetched server-side and included as context. In Ollama, Local LLM, or Web LLM mode the request runs entirely client-side and live marketplace data is not available — switch to Local CLI or Hosted API for data-driven reports.
Saving as a Report
After the AI responds, a Save as Report button appears under the reply. Clicking it saves the response as a named report in Ecommerce Reports, automatically titled with your question and the current month.
Frequently Asked Questions
x-amz-access-token header is sufficient. TotalApp keeps the optional AWS Role ARN field only for legacy apps still on the SigV4 contract./tokens/2021-03-01/restrictedDataToken automatically before calling the Orders API.ATVPDKIKX0DER) must use region na.