Skip to main content

Commerce (Medusa / Postgres)

Commerce uses Medusa's native modules (Postgres). We extend rather than replace. This page notes the entities we rely on and the extensions we add.

Native Medusa entities (used as-is)​

EntityUse here
Product, ProductVariant, ProductOptioncatalog/SKUs
ProductCategory, ProductCollection, ProductTagmerchandising
PriceList, PriceSet, MoneyAmounttiered pricing (D2C/dealer/distributor/project)
SalesChannelweb, app, dealer-b2b, amazon, flipkart, pos
Cart, LineItemcheckout
Order, Fulfillment, ReturnOMS
Promotion, Campaigndiscounts/coupons
InventoryItem, StockLocation, Reservationstock
Customer, CustomerGroupidentity + group pricing
PaymentCollection, PaymentSessionpayments (→ Hyperswitch)
TaxRegion, TaxRateGST base

Extensions (custom Medusa modules / metadata)​

Kit / BOM​

// custom module: a kit is a product flagged as a system, with components
Kit {
id: uuid
productId: string // the sellable "3kW Solar System"
components: Array<{ variantId: string; qty: number; role: 'panel'|'inverter'|'battery'|'structure'|'accessory' }>
configurable: boolean // drives the storefront configurator
}

Translation sidecar (commerce i18n)​

ProductTranslation {
productId: string
locale: string // e.g. hi-IN
title?: string
description?: string
// fallback to default locale when missing
}

Channel availability / pricing map​

ChannelListing {
productId: string
channel: 'web'|'app'|'dealer-b2b'|'amazon'|'flipkart'|'pos'
available: boolean
priceListId?: string // channel-specific price list
externalRef?: string // ASIN / Flipkart listing id
}

Compatibility & spares (lightweight relations)​

Stored in a NestJS catalog-extension service (Mongo) referencing Medusa IDs when richer than Medusa's model:

Compatibility { productId: string; compatibleWith: string[]; type: 'accessory'|'battery'|'spare' }
SparePart { sparePartProductId: string; fitsProductIds: string[] }

Pricing strategy (B2B nuance)​

  • D2C price = default region price.
  • Dealer/Distributor = CustomerGroup + dedicated PriceList per tier.
  • Project/quote pricing = generated via the lead/quote flow (Storefront) → one-off price on the cart, governed by DMS scheme rules.

Serial capture​

At dispatch, serials are attached to the order's line items (metadata) and emitted as serial.assigned for the Warranty registry. Medusa is not the asset registry — it only records the sale.

Migrations​

Run via Medusa CLI per deploy. Custom modules ship their own migrations.