Amazon SP-API Integration for Magento and WooCommerce: A Practical Guide

• May 25, 2026
• admin
• no comments

Amazon’s Selling Partner API replaced the older MWS (Marketplace Web Service) platform and brought significant changes to how merchants connect their eCommerce systems to Amazon’s marketplace infrastructure. The SP-API surface is broader, the authentication model is different, and the migration from MWS left a lot of existing integrations in a broken state.

For merchants running Magento or WooCommerce, integrating with Amazon SP-API directly means dealing with OAuth authentication, LWA (Login with Amazon) credential management, rate limiting, and the specific quirks of Amazon’s feed-based data synchronization model. Off-the-shelf plugins exist, but most handle the basic cases and fail under the edge cases that volume merchants encounter daily.

This guide covers what a production Amazon SP-API integration actually requires — specifically for Magento and WooCommerce — including the inventory sync architecture, order routing logic, label generation workflow, and the edge cases that are not covered in Amazon’s documentation.

SP-API vs MWS: What Changed and What It Means for Integrations

The core architectural shift from MWS to SP-API is the move from AWS Signature Version 2 to LWA (Login with Amazon) OAuth 2.0. This is not a minor update. It means every integration built on MWS credentials needs a complete re-authentication implementation. Refresh token management, access token rotation, and the SP-API role assignment model all need to be handled correctly for the integration to function at all.

Beyond authentication, SP-API introduced a rate limiting model based on leaky bucket algorithms rather than the simpler request quotas MWS used. Each API operation has its own burst and restore rate. Hitting these limits in production — especially during peak sync windows — causes silent failures if your error handling does not account for 429 responses correctly.

Authentication: LWA, OAuth, and Credential Rotation

SP-API authentication requires three credential sets: the LWA client ID and secret (registered in your developer application), the refresh token (granted when a seller authorizes your application), and the AWS IAM credentials for signing requests. All three need to be present and valid for every API call.

The access token derived from the refresh token expires in one hour. Your integration needs to cache it for the duration of its validity and refresh it proactively before it expires — not reactively after a 401. Reactive refresh causes race conditions in multi-threaded sync processes that are difficult to debug under production load.

Store refresh tokens encrypted at rest. They are long-lived credentials that grant ongoing access to the seller account. Treat them with the same security discipline as a private key.

Inventory Sync Architecture: Polling vs. Notifications

For inventory pushes from your system to Amazon, the SP-API Feeds API is the standard path. Submit a JSON or XML feed with your inventory quantities, poll the feed status endpoint until processing completes, then check for processing errors in the result document. This is synchronous in principle and asynchronous in practice — feed processing times under normal conditions range from under a minute to over ten minutes depending on catalog size and Amazon system load.

For order pulls from Amazon into your system, the SP-API Notifications API (via SQS) is preferable to polling the Orders API. Polling at five-minute intervals accumulates API quota faster than notifications and introduces latency into your order processing pipeline. Set up an SQS destination, subscribe to ORDER_CHANGE notifications, and process new orders in near-real-time.

The practical caveat: SQS notification delivery is not guaranteed to be in order. Two notifications for the same order may arrive out of sequence. Your order processing logic needs to handle this — typically by always fetching the current order state from the Orders API when processing a notification rather than trusting the notification payload alone.

Order Routing: FBA vs MFN and Multi-Warehouse Logic

Orders on Amazon arrive as either FBA (Fulfilled by Amazon) or MFN (Merchant Fulfilled Network) orders. FBA orders do not require you to generate shipping labels — Amazon handles fulfillment. But you still need to pull them for reconciliation, accounting, and inventory adjustment purposes.

MFN orders require you to confirm shipment via the SP-API Shipments endpoint within the handling time window you committed to. Miss that window and Amazon degrades your seller metrics. Your order routing logic needs to identify MFN orders, route them to the appropriate warehouse, generate a label, and confirm shipment — all within the handling time window.

For multi-warehouse merchants, the routing logic needs to consider inventory position at each location, carrier availability, and shipment cost. Amazon does not impose routing logic on you, but your seller metrics — specifically, on-time delivery rate and pre-fulfillment cancellation rate — will reflect the outcomes of whatever routing decisions you make.

Label Generation and Shipment Confirmation Workflow

Generating labels via the SP-API Merchant Fulfillment API is straightforward for standard shipments. The complexity emerges in the edge cases: orders with multiple packages, dangerous goods restrictions on certain product categories, and the mismatch between Amazon’s available carrier options and your negotiated carrier rates.

For merchants with volume carrier contracts, the economics usually favor generating labels outside of Amazon’s Merchant Fulfillment API (using your own carrier integration) and confirming the shipment via the Orders API with your own tracking data. Amazon’s Merchant Fulfillment rates are competitive for small parcels but rarely beat volume-contracted rates for heavier shipments.

Shipment confirmation must include a valid tracking number and carrier code that Amazon recognizes. Submit invalid carrier codes and the shipment confirmation is accepted but the tracking data does not populate in the buyer-facing order detail — generating “where is my order” contacts that affect your customer satisfaction metrics.

Reconciliation: Catching Discrepancies Before Amazon Does

Amazon’s reconciliation tooling catches discrepancies — between what you reported shipping and what the carrier confirms, between inventory you claim to have and what Amazon’s systems register. When Amazon catches a discrepancy, the resolution process is slow and the consequences for seller metrics can be significant.

Build reconciliation into your integration rather than relying on Amazon to surface problems. Daily reconciliation jobs that compare your OMS order state against SP-API order state, your inventory feed submissions against Amazon’s current inventory levels, and your shipment confirmations against carrier tracking events will catch most discrepancies within 24 hours — when they are easy to resolve.

Magento-Specific Implementation Notes

Magento’s inventory management — particularly MSI (Multi Source Inventory) — adds complexity to Amazon sync because the saleable quantity calculation involves source allocations that are not always directly mappable to the per-SKU quantity Amazon expects. Make sure your inventory sync reads the saleable quantity for the appropriate stock scope, not the aggregate source-level quantity.

Order import from Amazon into Magento should create orders in a custom state (not the standard pending state) to prevent Magento’s standard order processing workflows from triggering prematurely. Amazon orders need to flow through a separate fulfillment workflow that interacts with SP-API for label generation and shipment confirmation before updating order state in Magento.

WooCommerce-Specific Implementation Notes

WooCommerce’s inventory model is simpler than Magento MSI, which makes the sync implementation more straightforward — but variable products with multiple attribute combinations require careful SKU-to-variation mapping. Amazon’s catalog treats each variation as a separate ASIN or child ASIN. Your mapping table needs to handle the relationship between WooCommerce variation IDs and Amazon ASIN/seller SKU pairs.

WooCommerce’s order creation hooks make it relatively easy to import Amazon orders and have them appear in the standard WooCommerce order management interface. The integration complexity is in the fulfillment side — specifically, preventing WooCommerce’s standard email notifications from firing on Amazon orders and ensuring the WooCommerce stock decrement happens at the right point in the Amazon fulfillment workflow, not at order import time.