# Front Amazon SP-API

## When to use this

Amazon Selling Partner API enforces a shared concurrency limit per
application. Teams often spray Login with Amazon (LWA) credentials and create
one developer app per caller. Pin a regional SP-API host, store one refresh
token as a managed credential, and hand each caller a pool key.

Authorization-code click-to-connect and Restricted Data Tokens are out of
scope. Use a refresh token you already have from an existing Amazon app.

## Origins to pin

Pick the regional host your app already calls:

| Host | Region |
|---|---|
| `https://sellingpartnerapi-na.amazon.com` | North America |
| `https://sellingpartnerapi-eu.amazon.com` | Europe |
| `https://sellingpartnerapi-fe.amazon.com` | Far East |

One pool, one region. Put multiple hosts on one pool only when those hosts
must share the same concurrency budget.

## Setup

1. Create a pool and pin the SP-API origin under **Settings**.
2. On **Credentials**, add an **OAuth 2.0 refresh token** credential: LWA
   client id, client secret, and refresh token. Set the token URL to
   `https://api.amazon.com/auth/o2/token` and the access-token header to
   `x-amz-access-token`.
3. On the pool **Settings**, choose **Managed** custody and **OAuth 2.0
   refresh token**, then attach that credential.
4. Set **Max concurrency** to your safe Amazon limit (or use **Adaptive**
   with that value as the max).
5. Mint a pool key under **Access**.
6. Point callers at `https://‹pool›.nthpool.cloud/...` instead of the Amazon
   host. Send `X-Nthpool-Key`.

```bash
curl -sS "https://sp-na.nthpool.cloud/orders/v0/orders?MarketplaceIds=ATVPDKIKX0DER" \
  -H "X-Nthpool-Key: $POOL_KEY" \
  -H "Accept: application/json"
```

The edge exchanges the refresh token, caches the access token, and sends
`x-amz-access-token`. When the pinned origin is a
`sellingpartnerapi-*.amazon.com` host it also sends `x-amz-date` and, if
the caller omitted `User-Agent`, `nthbouncer`. Callers never see the LWA
secret or refresh token.

## Tips

- One Amazon developer app can serve many pool keys. Rotate the credential
  when you rotate the LWA secret; keys stay the same.
- Enable **Retry on 429** so transient Amazon throttles are absorbed at the
  edge.
- SigV4/IAM is not required for SP-API seller calls.

## See also

- [Credentials](/docs/credentials)
- [Pool settings](/docs/pools/settings)
- [Concurrency](/docs/pools/concurrency)