Skip to main content

3. Dealer & Distribution Management (DMS)

Purpose — Run the tiered channel that actually moves product: distributors → dealers/retailers → installers, with tier pricing, credit, targets, schemes, and loyalty. This is the "vendor" of the notes (precisely: channel partner — see Glossary).

Personas served​

Dealer, Distributor, Manager (scoped), Sales-rep, Super admin.

Key capabilities​

  • Multi-tier hierarchy — Company → Distributor → Dealer/Retailer → Installer; tier-specific pricing + credit.
  • Primary vs secondary sales — HQ→distributor and distributor→dealer tracking.
  • Onboarding & KYC — agreements, documents, territory/zone assignment.
  • Dealer portal/app — order booking, invoices, ledger / credit limit, stock visibility, leads.
  • Schemes & promotions — slabs, discounts per tier/region/period; offers/bonuses (notes).
  • Targets & incentives — sales targets, achievement, payout; sales-rep beat plans, field-force tracking.
  • Loyalty for partners — dealers/installers/electricians (scan-QR → points; Luminous/Exide-style). Shared engine with CRM & Loyalty.
  • Dealer locator — store finder by pincode/geo on the storefront.
  • Channel serial tracking — QR/barcode/serial through the channel (anti-counterfeit, gray-market control); ties to Warranty.
  • Manager data-scoping — across all partners or only assigned ones (RBAC).

Data owned​

Mongo (DMS): ChannelPartner, tiers, KYC, territories, targets, schemes, beat plans. Postgres (Finance): dealer ledgers, credit, payouts (financial truth). Orders flow through Medusa. See dms-partners-loyalty.

Events​

  • Emits: dealer.onboarded, dealer.target.updated, scheme.published, secondary_sale.recorded.
  • Consumes: order.placed (attribute to partner), payment.captured (ledger), serial.assigned (channel tracking).

APIs​

  • POST /dms/partners, GET /dms/partners (scoped), POST /dms/partners/:id/kyc
  • GET /dms/partners/:id/ledger, POST /dms/orders, GET /dms/targets (scoped)
  • GET /dms/locator?pincode=, POST /dms/schemes

Tenant-config knobs​

Tier definitions; credit policy defaults; scheme templates; featureFlags.loyalty/affiliate; locator visibility.

Dependencies​

Orders, Finance, CRM & Loyalty, RBAC.

Open questions​

  • Credit/collections workflow depth in v1?
  • Does any tenant need a true marketplace (independent sellers + payout splitting) vs this channel model? (Different build — flagged in plan.)