Overview
Amazon's Selling Partner API (SP-API) is the REST API that replaces the legacy Amazon MWS (Marketplace Web Service) for programmatic access to Amazon seller and vendor data. It covers the full range of Amazon marketplace operations — listing management, order retrieval and fulfilment, inventory management, pricing, reports, financial data, advertising, and the brand analytics that registered brands access. For businesses that sell on Amazon and manage their Amazon operations through custom software, ERP systems, or operational tools, the SP-API is the integration point that makes programmatic Amazon management possible.
The SP-API is one of the more complex third-party API integrations to build correctly. Authentication uses AWS Signature Version 4 with Login with Amazon (LWA) OAuth tokens — a two-layer authentication system where LWA provides the seller authorisation and AWS SigV4 signs each individual request. Rate limiting varies by API section and is enforced strictly, with request rates and burst limits that differ between endpoints. The API covers multiple business models — sellers (who ship to customers), vendors (who sell wholesale to Amazon), and advertising clients — each with different access patterns and data structures. Building an SP-API integration that is reliable, handles rate limits correctly, and covers the operations the seller actually needs requires specific knowledge of the API's structure and behaviour.
We build Amazon SP-API integrations for Amazon sellers, multi-channel retailers, Amazon service providers, and software platforms that need to connect their operations to Amazon marketplace data — order management, listing synchronisation, inventory updates, pricing automation, financial reconciliation, and the reporting that Amazon operations require.
What Amazon SP-API Integration Covers
Authentication and authorisation. SP-API authentication is the most technically demanding aspect of the integration — a two-layer system that combines Amazon's Login with Amazon (LWA) OAuth flow for seller authorisation with AWS Signature Version 4 for request signing.
LWA token management: the OAuth 2.0 access token issued by Login with Amazon that authorises the application to act on behalf of a specific seller. LWA tokens expire after one hour and must be refreshed using the refresh token obtained during the OAuth authorisation flow. Token refresh management — requesting a new access token before the current one expires, handling refresh failures, and storing tokens securely. The LWA client credentials (client ID and client secret) registered in Amazon Developer Central alongside the seller-specific refresh token obtained through the authorisation grant flow.
AWS Signature Version 4: the request signing algorithm that Amazon requires for SP-API calls. Every SP-API request must include an Authorization header computed from the request method, URL, headers, and body using HMAC-SHA256 with AWS credentials. The SigV4 signing process: create the canonical request, create the string to sign, calculate the signature, assemble the authorization header. The AWS IAM role with the execute-api:Invoke permission that authorises the SP-API calls, assumed using AWS STS for role-based access.
Authorisation grant flow: the OAuth authorisation flow that sellers use to grant an application access to their Amazon data. The authorisation URL with the application client ID, the redirect URI, and the required scopes. The authorisation code received at the redirect URI, exchanged for access token and refresh token. The seller-specific credentials management that allows the integration to manage multiple seller accounts from a single application.
Orders API. The SP-API Orders section for retrieving and managing customer orders.
Order retrieval: the getOrders endpoint that returns orders matching specified criteria — created after a specific date, with specific order statuses (Pending, Unshipped, Shipped, Cancelled), for specific marketplaces. Paginated order retrieval using the next token returned when more orders are available than the single response contains. Order detail retrieval with getOrder and getOrderItems for the full order information including line items, shipping address, buyer information, and order-level charges.
Order status tracking: monitoring orders as they progress through Amazon's fulfilment workflow. Tracking Pending orders that are waiting for payment confirmation, Unshipped orders that need to be fulfilled, Shipped orders where tracking information should be submitted, and Cancelled orders that need to be handled in the seller's system.
Fulfilment confirmation: for Fulfilled by Merchant (FBM) sellers, the createShipment submission that confirms shipment of an order and provides the tracking number. The carrier code and tracking identifier from the shipping label submitted back to Amazon to confirm the order has been shipped.
Order sync patterns: the incremental order sync that retrieves orders modified after a specific timestamp, avoiding re-processing of previously synced orders. The date window that covers the API's response time to ensure no orders are missed at the boundary of each sync window.
Listings API. Managing product listings on Amazon — creating, updating, and managing the catalogue data that Amazon displays to customers.
Listing retrieval: the getListingsItem endpoint that returns the current state of a listing — the attributes, the offers, the fulfilment availability, and any issues Amazon has flagged with the listing. The searchListingsItems endpoint for finding listings by ASIN, SKU, or other identifiers.
Listing creation and updates: the putListingsItem endpoint that creates or replaces a listing, and the patchListingsItem endpoint that updates specific attributes of an existing listing. The product type definition that specifies which attributes are required and which are optional for each product type. The Amazon product type taxonomy that determines the correct product type for each listing.
Issues and suppression: the listing issues that Amazon reports when a listing has problems — missing required attributes, policy violations, image issues. The issue codes and their resolution steps. Listings that Amazon has suppressed from search results due to quality or policy issues, and the remediation required to restore them.
Offer management: the pricing and availability data that determines how the seller's listing appears in Amazon's buy box. The quantity and price attributes that set the inventory level and selling price for each listing. The marketplace-specific offer data for sellers active on multiple Amazon marketplaces.
Feeds API. Bulk operations through Amazon's feed submission system — the mechanism for processing large numbers of listing updates, inventory changes, and pricing modifications that the individual listing endpoints cannot handle efficiently at scale.
Feed submission: the createFeed endpoint that submits a feed document to Amazon for processing. The feed type that specifies what kind of data the feed contains — POST_PRODUCT_DATA for catalogue data, POST_INVENTORY_AVAILABILITY_DATA for inventory, POST_PRODUCT_PRICING_DATA for pricing. The feed document upload to the pre-signed S3 URL provided by Amazon before submitting the feed.
Feed processing status: the getFeed endpoint that returns the current processing status of a submitted feed. Polling the feed status until it reaches a terminal state (DONE, CANCELLED, FATAL). The feed processing report retrieved after completion that describes the results — the records processed successfully and the records that failed with their error messages.
Feed types: the JSON and XML feed formats for different update types. The JSON-based JSON_LISTINGS_FEED for catalogue attribute updates using the SP-API's newer listing format. The XML-based legacy feeds (_PRODUCT_DATA_, _INVENTORY_, _PRICING_) for bulk operations that the newer API does not yet fully replace.
Inventory API. Managing FBA (Fulfilled by Amazon) and FBM inventory levels visible to Amazon customers.
FBA inventory: the getInventorySummaries endpoint that returns FBA inventory levels — the sellable, unsellable, reserved, and inbound inventory quantities for each ASIN. The inventory health data that identifies ageing inventory approaching long-term storage fee thresholds. The reorder trigger logic that monitors FBA inventory levels and signals when replenishment shipments to Amazon fulfilment centres should be created.
Inventory updates for FBM: the putListingsItem endpoint with updated quantity attribute for FBM inventory level changes. The inventory sync that keeps Amazon's displayed stock level aligned with the seller's actual available inventory. The inventory buffer strategy that reserves a portion of total inventory as a safety stock, preventing overselling when inventory is shared across multiple channels.
Multi-location inventory: for sellers with inventory in multiple warehouses or fulfilment locations, the inventory management that correctly attributes available quantity to the fulfilment location that will actually ship the order.
Pricing API. Reading and managing Amazon product pricing.
Competitive pricing: the getCompetitivePricing endpoint that returns the current buy box price and the competitive prices from other sellers for each ASIN. The pricing data that automated repricing logic uses to adjust prices in response to competitor pricing.
Offer listings: the getItemOffersBatch endpoint that returns all seller offers for a set of ASINs — the price, condition, shipping options, and prime eligibility of each offer. The market position data that informs pricing strategy.
Pricing updates: the patchListingsItem endpoint for individual price updates, and the pricing feed for bulk price updates. The pricing automation that monitors competitive pricing and adjusts prices according to the seller's repricing rules.
Reports API. Amazon's scheduled and on-demand reports for operational data that the SP-API endpoints do not provide directly.
Report types: the financial reports that provide settlement data — GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE for the settlement payment data that financial reconciliation requires. The inventory reports — GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA for FBA inventory snapshots. The order reports — GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL for bulk order data. The performance reports — GET_SELLER_FEEDBACK_DATA for customer feedback metrics.
Report request and retrieval: the createReport endpoint that requests report generation, the getReport polling to check completion status, and the report document download from the S3 URL provided when the report is ready. The report parsing that converts Amazon's tab-delimited or JSON report formats into structured data for processing.
Scheduled reports: the createReportSchedule endpoint that configures Amazon to automatically generate reports on a defined schedule — daily settlement reports, weekly inventory snapshots, monthly performance summaries. The scheduled report that ensures critical operational data is always available without requiring on-demand report requests.
Financial API. Amazon financial events for accounting and reconciliation.
Financial event groups: the listFinancialEventGroups endpoint that returns settlement periods — the Amazon payment cycles during which transactions are grouped and settled. The settlement period date ranges used to scope financial event retrieval.
Financial events: the listFinancialEvents endpoint that returns the individual financial transactions within a settlement period — order charges, shipping credits, promotional rebates, FBA fees, referral fees, and the other line items that make up each settlement. The financial event data that accounting systems use to reconcile Amazon payments against the seller's own records.
Fee reconciliation: matching the fees Amazon charges against the seller's expected fee schedule — identifying unexpected fee types, verifying that fee amounts are within expected ranges, and flagging discrepancies for review.
Notifications API. Real-time event notifications via Amazon's notification system — the mechanism for receiving push notifications when Amazon events occur rather than polling for changes.
Notification subscriptions: the createSubscription endpoint that registers the integration to receive notifications for specific event types. The notification destination — an SQS queue or EventBridge event bus — where Amazon delivers notification messages.
Notification types: ORDER_CHANGE for real-time order status updates, LISTINGS_ITEM_STATUS_CHANGE for listing suppression and reinstatement events, REPORT_PROCESSING_FINISHED for report completion, FBA_OUTBOUND_SHIPMENT_STATUS for FBA shipment status changes. The notification processing that handles each event type and triggers the appropriate action in the seller's system.
SQS queue processing: the consumer that reads notification messages from the SQS queue, parses the notification payload, and processes the event. The SQS visibility timeout and message deletion pattern that ensures notifications are processed exactly once without loss.
Rate Limit Management
Amazon enforces strict rate limits on SP-API endpoints, with different limits for each API section. Rate limit violations return 429 responses and can trigger temporary throttling that exceeds the per-request limit.
Rate plan awareness. Each SP-API endpoint has a documented rate and burst limit — for example, getOrders allows 0.0167 requests per second (one per minute) with a burst of 20. Understanding the rate plan for each endpoint used by the integration is the prerequisite for designing request scheduling that respects the limits.
Token bucket implementation. The token bucket algorithm that models Amazon's rate limiting — tokens accumulate at the rate limit rate up to the burst limit, and each request consumes one token. The client-side token bucket that prevents the integration from exceeding the rate limit even under high load. The request queue that buffers requests when the token bucket is empty, releasing them as tokens accumulate.
Retry with backoff. The retry logic that handles 429 responses — exponential backoff with jitter that retries throttled requests after a progressively increasing delay. The x-amzn-ratelimit-limit response header that Amazon includes in 429 responses indicating the limit that was exceeded. The maximum retry count and the circuit breaker that stops retrying when a limit is persistently exceeded.
Multi-Marketplace Support
Amazon SP-API operates across multiple marketplaces — Amazon.com (US), Amazon.co.uk (UK), Amazon.de (DE), Amazon.fr (FR), Amazon.nl (NL), Amazon.es (ES), and others — each with a distinct marketplace identifier and, for some regions, a distinct endpoint.
Marketplace IDs: the MarketplaceIds parameter accepted by most SP-API endpoints that scopes the request to specific marketplaces. The marketplace ID for Amazon.nl (A1805IZSGTT6HS) and the other European marketplace IDs for European sellers.
Regional endpoints: the SP-API endpoint base URLs that differ by region — sellingpartnerapi-eu.amazon.com for European marketplaces, sellingpartnerapi.amazon.com for North American marketplaces. The region-appropriate endpoint configuration for each seller's active marketplaces.
Cross-marketplace reporting: aggregating data across multiple marketplaces for sellers active in several markets — the combined order volume, the inventory position by marketplace, the financial performance by marketplace.
Technologies Used
- C# / ASP.NET Core — primary SP-API integration implementation with the .NET HTTP client, AWS SDK for SigV4 signing, and JSON processing
- Rust / Axum — high-performance order processing and inventory management for high-volume Amazon sellers
- Python — SP-API scripting, report processing, and data analysis pipelines
- AWS SDK — SigV4 request signing and STS role assumption for SP-API authentication
- AWS SQS — notification processing queue for real-time Amazon event delivery
- AWS EventBridge — alternative notification delivery for complex event routing
- SQL (PostgreSQL / MySQL) — order data storage, inventory tracking, financial reconciliation data
- Redis — rate limit token bucket state, caching of Amazon reference data, job coordination
- Hangfire / scheduled jobs — scheduled synchronisation for orders, inventory, and reports
- Docker — containerised integration service deployment
- GitHub Actions — CI/CD pipeline for integration service deployment
Amazon SP-API in Multi-Channel Operations
For businesses selling across multiple channels — Amazon alongside their own website, other marketplaces, and physical retail — the SP-API integration is one component of the multi-channel inventory and order management architecture. Amazon orders sync into the central order management system alongside orders from other channels. Inventory updates from the central inventory system push to Amazon's available quantity. Financial data from Amazon settlements reconciles against the central financial records.
The SP-API integration in this context is the Amazon channel connector — the component that translates between Amazon's data model and the operational systems that manage inventory, orders, and finances across all channels. Correct implementation means that the multi-channel operation's central systems always reflect the accurate Amazon position without manual reconciliation between Amazon Seller Central and the central systems.
Amazon Operations, Connected to Your Systems
Amazon SP-API integrations built for the operational scale that Amazon selling requires — correct authentication, rate-limit-respecting request management, comprehensive order and inventory synchronisation, financial data for reconciliation, and the real-time notifications that keep your systems aligned with Amazon's event stream.