Amazon — Multi-marketplace setup and product limits

One integration per marketplace

Amazon treats each marketplace as a completely separate storefront. Each Amazon marketplace requires its own EcartAPI integration — a separate OAuth flow that produces a separate shop_id and access_token.

What is shared	What is NOT shared
Your EcartAPI app (App ID, credentials)	Access tokens — one per marketplace
API version setting (v1 or v2)	Store data — listings, orders, inventory
Webhook subscriptions logic	Webhook subscriptions — must be created per marketplace token

If your customer sells on Amazon US and Amazon MX, you need two integrations: one OAuth flow per marketplace. You will receive two redirect callbacks with two different shop_id values.

Webhook subscriptions are marketplace-scoped

Webhook subscriptions are tied to a specific store token. A subscription created with the Amazon US token will only fire for events from that marketplace. You must create separate webhook subscriptions for each marketplace you want to receive notifications from.

When a webhook fires, use the URL path pattern you registered to identify which marketplace triggered the event (see Webhooks for the recommended URL pattern).

Product list: the 1,000-item limit

Amazon's own searchListingsItems API caps results at 1,000 items per query. This is an Amazon-imposed limit, not an EcartAPI restriction — it cannot be bypassed with pagination alone.

If your catalog has more than 1,000 products on a given marketplace, a single GET /api/v2/products call will not return the full catalog.

Workaround: date-range filtering

Split your catalog retrieval into multiple date-range windows. EcartAPI's products endpoint supports the following filters:

Filter	Description
`createdAt[from]`	Return products created on or after this date (ISO 8601).
`createdAt[to]`	Return products created on or before this date (ISO 8601).
`updatedAt[from]`	Return products updated on or after this date (ISO 8601).
`updatedAt[to]`	Return products updated on or before this date (ISO 8601).

Combine these with sort direction to paginate through large catalogs without hitting the 1,000-item ceiling:

# First window: products created in Jan 2024
GET /api/v2/products?createdAt[from]=2024-01-01&createdAt[to]=2024-01-31&sort=asc

# Second window: products created in Feb 2024
GET /api/v2/products?createdAt[from]=2024-02-01&createdAt[to]=2024-02-28&sort=asc

Continue narrowing the date window until each slice returns fewer than 1,000 items. For catalogs with heavy activity in a short period, narrow the window further (weekly or daily).

Keeping the catalog in sync

For ongoing sync, use updatedAt[from] with the timestamp of your last successful sync to retrieve only products that changed since then:

GET /api/v2/products?updatedAt[from]=2024-06-01T00:00:00Z&sort=asc

This incremental approach avoids re-fetching the entire catalog on every sync cycle and stays well below the 1,000-item limit for most update windows.

Filtering by marketplace

When a single integration spans multiple marketplaces (not common, but possible depending on Amazon SP-API setup), use the marketplaceId filter to scope requests to a specific marketplace:

GET /api/v2/products?marketplaceId=ATVPDKIKX0DER

→ Amazon — API Version Setup — v1 vs v2 differences and how to configure the version.
→ Amazon — Easy Ship Shipping Label — Retrieving the label for Easy Ship orders.
→ Webhooks — How webhook subscriptions work and how to identify the source marketplace.
→ Store identification — How shop_id works across multiple marketplace integrations.