Marketplaces — Amazon & Flipkart
Decision: Amazon and Flipkart are sales channels (notes #1) synced via custom connectors — there is no off-the-shelf Medusa plugin for Amazon SP-API or the Flipkart Seller API. Each is a NestJS connector service mapped to a Medusa sales channel.
What "channel" means here
Selling your products onto Amazon/Flipkart (your listings on their marketplaces), then pulling their orders back into the unified OMS. This is not the same as putting Amazon/Flipkart products on your store.
Connector responsibilities
| Direction | Sync |
|---|---|
| Out → marketplace | listings (title/price/images), inventory levels, price updates |
| In ← marketplace | orders, cancellations, returns, settlement/fees |
| Status | acknowledge, confirm dispatch (AWB), tracking |
Mapping
- Each marketplace = a Medusa SalesChannel (
amazon,flipkart). ChannelListing(commerce model) holdsexternalRef(ASIN / Flipkart listing id) + channel price list.- Inbound orders create Medusa orders tagged with the channel; fulfilled via the marketplace's own logistics or self-ship per policy.
Sync mechanics
- Scheduled pulls (orders, inventory drift reconciliation) via BullMQ cron.
- Push on change (inventory/price) on
inventory.changed/price.updatedevents. - Idempotent upserts keyed by external IDs; rate-limit aware (marketplace API quotas).
- Failures → DLQ + alert; never silently drop a marketplace order.
Reconciliation
Marketplace settlements/fees flow to Finance for reconciliation against orders.
Phase
Marketplace connectors are v2 in the roadmap — the self storefront + dealer channels ship first.
Tenant config
featureFlags.amazonChannel/flipkartChannel, AMAZON_SPAPI_* / FLIPKART_* creds (secret), per-channel price lists, fulfillment policy (marketplace-fulfilled vs self-ship).
Open questions
- FBA / marketplace-fulfilled vs self-ship default per tenant.
- Catalog mapping source of truth when listings differ from D2C content.