Amazon

Amazon is the most demanding channel to integrate. Listings hinge on ASIN (Amazon's product identifier), inventory branches into seller-fulfilled vs FBA, and the SP-API has tight rate limits and region-specific endpoints. This page collects the quirks the Sales Channel module already handles and the ones you need to know about as an integrator.

SP-API, not MWS

The legacy MWS API was deprecated in 2024. The Sales Channel Amazon provider calls the Selling Partner API (SP-API). That means:

• LWA (Login with Amazon) OAuth issues access tokens; access tokens are short-lived (1 hour) and refresh tokens are long-lived.
• Every request is signed with AWS Signature v4 against the SP-API endpoint.
• Endpoints are region-specific: NA (https://sellingpartnerapi-na.amazon.com), EU (https://sellingpartnerapi-eu.amazon.com), FE (https://sellingpartnerapi-fe.amazon.com).
• Sellers must have an SP-API app registered in Amazon Seller Central, and the integration's applicationId must match.

When enabling Amazon, pass:

{
  "sellerId": "A1B2C3D4E5F",
  "marketplaceId": "ATVPDKIKX0DER",
  "region": "na"
}

marketplaceId is the Amazon marketplace (US: ATVPDKIKX0DER, UK: A1F83G8C2ARO7P, DE: A1PA6795UKMFR9, etc.). One Amazon account can sell across multiple marketplaces — enable the channel once per marketplace.

ASINs and SKUs

Amazon listings are matched by ASIN (10-char product identifier). Sellers list against an existing ASIN (matching an existing catalog entry) or create a new one (requires UPC/EAN/GTIN). Your internal SKU is just a label — the ASIN is what Amazon enforces.

The channel mapping for Amazon stores sku → asin. Inventory and pricing pushes look up the ASIN; if missing, the push fails with mapping_missing.

{
  "channel": "amazon",
  "sku": "SKU-100",
  "channelSku": "B08XXXXXX",
  "metadata": { "fulfillment": "FBA" }
}

For brand-new ASIN creation, use the Listings API path through POST /sales-channel/channels/amazon/execute with operation: "create_listing". This requires a UPC unless you're brand-registered.

FBA vs FBM

Amazon listings are either Fulfilled by Amazon (FBA, Amazon ships from FBA warehouses) or Fulfilled by Merchant (FBM, you ship). The channel mapping flags fulfillment type per SKU.

Fulfillment	Inventory source of truth	Order fulfillment
FBA	Amazon (you pull-in)	Amazon ships automatically
FBM (or MFN)	Master in Storefront	You ship; writeback tracking

For FBA SKUs, set the conflict strategy to channel_wins so Amazon's inventory feed updates master after each FBA decrement. For FBM SKUs, use master_wins.

Rate limits

SP-API enforces per-operation rate limits using a leaky-bucket algorithm. The provider observes the x-amzn-RateLimit-Limit header and queues requests. Typical limits:

• getOrders: 0.0167 req/s (1 every 60s) with burst of 20.
• getInventorySummaries: 2 req/s, burst 30.
• submitFeed: 0.0083 req/s (1 every 2 minutes), burst 15.

The module config caps Amazon at 30 requests/min, 36,000/day. Heavy bulk operations should use feeds (POST_FLAT_FILE_INVLOADER_DATA for inventory, POST_FLAT_FILE_PRICEANDQUANTITYONLY_UPDATE_DATA for prices) rather than per-SKU API calls — feeds are async and avoid hitting the throttle.

Order webhooks via SQS

Amazon doesn't push to a webhook URL directly. SP-API publishes notifications to an Amazon SNS topic; you subscribe an SQS queue, and the Sales Channel module polls the queue. During channel enable, the provider creates the SQS queue and the SNS subscription if enableNotifications: true.

Notifications cover order created, order status change, fulfillment updates, and (optionally) FBA inventory level updates.

ASIN gating and listing approval

Some categories (jewelry, watches, automotive parts) are gated. Selling there requires Amazon approval. The provider reflects gated-category errors as category_restricted in sync history. There's no auto-fix — the seller has to apply for approval through Seller Central.

Buy Box pricing

Amazon's Buy Box rotates between sellers based on price, fulfillment method, and seller metrics. To win Buy Box, use a match_competitor pricing rule on Amazon with a small undercutPercent (often 0.5–1%) and pair it with competitor price entries pulled via the Pricing API or scraped via a third-party.

Common error codes

Error	Meaning	Action
InvalidInput	Malformed payload	Verify field names against SP-API model docs
Unauthorized	LWA token expired	Refresh runs automatically; if persistent, re-OAuth
QuotaExceeded	Rate limit	Wait for the bucket to refill; switch to feeds
ResourceNotFound	ASIN doesn't exist	Map a different ASIN or create a new listing
Throttled	Burst limit exceeded	Retry with backoff (handled automatically)

Practical setup checklist

1. 1

   Get an SP-API app

   Register an app in Amazon's Developer Console under your seller account. Note the applicationId and the encryption keys.

2. 2

   Set the marketplace

   Decide which Amazon marketplace this connection covers. One channel connection per marketplace.

3. 3

   Configure FBA SKUs

   Set conflictStrategy: "channel_wins" for any SKU you fulfill via FBA. The master will track Amazon's reported inventory.

4. 4

   Plan for feeds

   If you have more than 1,000 SKUs, plan inventory and price syncs via feeds, not per-SKU calls. The bulk flag is on POST /sales-channel/inventory/sync/amazon — set useFeed: true in the body.