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/kycGET /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.)