Skip to main content

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​

DirectionSync
Out → marketplacelistings (title/price/images), inventory levels, price updates
In ← marketplaceorders, cancellations, returns, settlement/fees
Statusacknowledge, confirm dispatch (AWB), tracking

Mapping​

  • Each marketplace = a Medusa SalesChannel (amazon, flipkart).
  • ChannelListing (commerce model) holds externalRef (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.updated events.
  • 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.