Amazon Adapter

Overview

The Amazon adapter integrates NexusCommerce with the Amazon Selling Partner API (SP-API). It supports catalog management, order fulfillment, inventory sync, competitor price monitoring, Buy Box tracking, and advertising data retrieval.

Amazon is typically the highest-volume marketplace for most sellers. The adapter is designed for reliability at scale, with robust rate limit handling and support for multiple Amazon marketplaces (US, UK, DE, FR, IT, ES, CA, JP, etc.) from a single connection.

Key Concepts

SP-API — Amazon's Selling Partner API, which replaced the older MWS API. Uses OAuth 2.0 with Login with Amazon (LWA) for authentication. All SP-API operations require a refresh token obtained via the seller's consent.

Marketplace ID — Amazon operates separate marketplaces per country. Each has a unique marketplace ID. A single seller account may have permission to sell in multiple marketplaces — create one NexusCommerce connection per marketplace.

Common marketplace IDs:

ASIN — Amazon Standard Identification Number. The marketplace-native product identifier. NexusCommerce maps ASINs to your internal SKUs.

FBA — Fulfilled by Amazon. For FBA products, Amazon manages inventory and shipping. NexusCommerce reads FBA inventory levels from the SP-API Inventory API (read-only).

Buy Box — Amazon's featured offer mechanism. The adapter fetches Buy Box data for monitored ASINs via the Pricing API.

Getting Started

Required Credentials

Required SP-API Permissions

When creating your SP-API application, request these role permissions:

• Catalog Items
• Orders
• Reports
• Feeds
• Inventory
• Pricing
• Product Advertising API (for ad data, if using Ads)

OAuth Flow

1. Create an SP-API application in Seller Central (Apps & Services > Develop Apps)
2. Note the Client ID and Client Secret
3. Direct the seller to the Amazon authorization URL to consent and obtain the authorization code
4. Exchange the authorization code for a refresh token via the LWA token endpoint
5. Store the refresh token in NexusCommerce

NexusCommerce handles token refresh automatically. Access tokens expire after 1 hour; the adapter refreshes them using the stored refresh token before each API call batch.

Features

Catalog Sync

The adapter syncs catalog data using the SP-API Catalog Items API and Reports API:

• Listings — Fetched via the GET_MERCHANT_LISTINGS_ALL_DATA report
• Product detail — Fetched per ASIN via GET /catalog/2022-04-01/items/{asin}
• Images — Main image URL included in catalog response
• Categories — Amazon browse node hierarchy mapped to NexusCommerce categories

Order Sync

Orders are fetched via GET /orders/v0/orders with status filter and date range. The adapter paginates through all pages automatically.

For each order, line items are fetched via GET /orders/v0/orders/{orderId}/orderItems.

Order Mapping:

Amazon order statuses map to NexusCommerce statuses:

Inventory Sync

For FBM inventory: the adapter pushes inventory updates via the Feeds API using the POST_INVENTORY_AVAILABILITY_DATA feed type. NexusCommerce generates the XML feed and submits it.

For FBA inventory: the adapter reads FBA inventory via GET /fba/inventory/v1/summaries. FBA quantities are stored in NexusCommerce but marked read-only.

Pricing

Price updates are submitted via the Feeds API using the POST_PRODUCT_PRICING_DATA feed type. The adapter generates a flat-file feed with SKU, price, and marketplace ID.

Competitor prices are fetched via GET /products/pricing/v0/competitivePricing for monitored ASINs.

Buy Box status is fetched via GET /products/pricing/v0/listing/items/{sellerId}/offerType/{offerType}.

Shipment Confirmation

Shipment confirmations are submitted via the Feeds API using the POST_ORDER_FULFILLMENT_DATA feed type. Required fields: AmazonOrderId, MerchantOrderItemID, ShippedDate, CarrierCode, TrackingNumber.

Configuration