Connect Amazon SP-API: pull orders in, push fulfillment out

Get your Seller ID, LWA credentials and refresh token in Seller Central, add AWS IAM signing keys, paste all eight fields into Integration, test, map, activate.

The Amazon SP-API connector pulls your Amazon orders into OMS, and pushes fulfillment, products, and inventory back to Amazon; it can also pull returns. It is built for merchant-fulfilled (MFN) orders — orders you ship yourself. One connection covers one seller account and one marketplace.

Prerequisites#

• An Amazon seller account with Seller Central access, selling merchant-fulfilled (MFN) orders.
• Permission in Seller Central to develop apps and authorize your app (Apps & Services → Develop apps).
• An AWS account with IAM access, so you can create an access key and attach the SP-API IAM policy for signing.
• Know which marketplace your store belongs to — the Marketplace ID must match that site (US: ATVPDKIKX0DER).

Get your credentials#

1. Step 1 — Seller ID: in Seller Central, go to Settings → Account info and copy the Merchant token. That is your Seller ID; it starts with A.
2. Step 1 — App credentials: in Seller Central, go to Apps & Services → Develop apps, open your app, and copy the LWA Client Identifier (starts with amzn1.application-oa2-client.) and the LWA Client secret.
3. Step 1 — Refresh token: authorize your app for your seller account and copy the refresh token you receive. It is a long-lived token and starts with Atzr|.

1. Step 2 — AWS access key: in the AWS Console, go to IAM → Security credentials and create an access key. The access key ID starts with AKIA.
2. Step 2 — Secret key: copy the AWS secret access key shown on the same page. It is shown only once.
3. Step 2 — IAM policy: make sure the IAM user or role behind the key has the SP-API IAM policy attached — without it, signing works but Amazon returns 403.
4. Step 2 — Role ARN (optional): if you sign through a cross-account IAM role, note its role ARN. Leave it out if you sign directly with the access key.

Fill it into Integration#

1. Open Integration → Connector Marketplace → Amazon SP-API → New connection.
2. Seller ID (Merchant token) — required: the Merchant token from Seller Central → Settings → Account info. It starts with A.
3. Marketplace ID — required: the ID of your store’s site. For the US marketplace use ATVPDKIKX0DER; for other sites, check the Amazon SP-API documentation.
4. LWA Client ID — required: the LWA Client Identifier from Seller Central → Apps & Services → Develop apps. It starts with amzn1.application-oa2-client.
5. LWA Client secret — required: the secret shown on the same Develop apps page. Encrypted at rest, never echoed back.
6. Refresh token — required: the long-lived refresh token you received when you authorized the app. It starts with Atzr|.
7. AWS access key ID — required: the IAM access key ID used for SigV4 signing. It starts with AKIA.
8. AWS secret access key — required: the secret paired with that access key, copied from IAM → Security credentials. It was shown only once.
9. IAM role ARN — optional: a cross-account IAM role ARN. If filled, signing first assumes that role via STS for temporary credentials; if left empty, the access key signs directly.

Test the connection#

Test runs two levels: connectivity (LWA authorization plus SigV4 signing both work) and a document-level preview (pull one real order and show platform fields → standard order side by side). If the store has no orders yet, place a test order on Amazon first — the preview needs one real document. If the test fails, note the exact error and check the FAQ below before changing fields at random.

Mapping / pick a template#

Pick the Amazon SP-API standard template. It maps order number, line SKUs, quantities, ship-to address, and fulfillment status for merchant-fulfilled orders. Check the mapping preview against one real order before activating — especially SKU matching, so each Amazon SKU pairs to the right OMS product.

Activate#

After activation, Integration pulls new merchant-fulfilled orders and returns on the schedule you set, and pushes fulfillment with tracking, plus product and inventory updates, back to Amazon. Watch the first few orders in Runs / Logs before trusting it unattended.

FAQ#

Test fails with 403

Why: this is usually a signing problem. The AWS access key or secret is wrong, or the IAM user or role behind the key does not have the SP-API IAM policy attached, so Amazon rejects the signed request.

Fix: re-copy the AWS access key ID (starts with AKIA) and secret from IAM → Security credentials, then in IAM confirm the SP-API policy is attached to that user or role. If you filled a role ARN, confirm that role exists and can be assumed. Then test again.

Refresh token is rejected or authorization is incomplete

Why: the refresh token does not match the LWA Client ID and secret, or the app authorization for your seller account was never finished, so Amazon cannot exchange the token for access.

Fix: in Seller Central → Apps & Services → Develop apps, finish authorizing the app for your seller account, copy the fresh refresh token (starts with Atzr|), and make sure the LWA Client ID and secret come from that same app. Paste all three together, then test again.

Orders from the wrong site, or no orders at all

Why: the Marketplace ID does not match the site your store actually sells on. The connection can still test OK, but Amazon only returns orders for the marketplace you named.

Fix: check which site your store belongs to and fill that site’s Marketplace ID — ATVPDKIKX0DER for the US marketplace; for other sites, look the ID up in the Amazon SP-API documentation. Save and run a manual pull to confirm orders arrive.

Seller ID is not accepted

Why: the value filled in is not the Merchant token — for example, a store name, an email, or another account ID. Amazon expects the Merchant token from your account info as the Seller ID.

Fix: in Seller Central, go to Settings → Account info, copy the Merchant token exactly as shown (it starts with A), paste it as the Seller ID, and test again.