Commerce Phase A Built
Commerce is the business-structure module: it lets a business owner set up an Organization (the brand) and one or more Merchants (the legal point-of-sale units where transactions happen), each with its own sale channels and product categories. It is the first thing a new user touches - onboarding creates the whole structure in one atomic step - and everything else (products, orders, inventory, finance) hangs off the merchant it creates.
Status: Built (P1) · In-progress (P2 Retail) · Owner: Hải Cao · Phase: 1-2 · Last reviewed: 2026-06-11
Chain Link Roadmap Phase 2 - By Month › July Epic BANA-1319 - Retail business type · BANA-1337 - Backoffice portal URD URD - new increment: RTLRetailPRD PRD-ORG-001 Organization & merchant · PRD-RCP-001 Receipt templates · PRD-FLR-001 Table & floor allocation · PRD-RTL-001 Retail · PRD-BOP-001 Backoffice portal (catalogue) Decisions (ADR) @nx/commerce decisions Dev docs @nx/commerce Delivery log Traceability matrix
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-03 |
| Tier | Core |
| Status | Built |
| Phase | P1 (Onboarding) · P2 (Full management) |
| Priority | HIGH |
| Primary users | Business Owner · Manager · (read access for Employees) |
2. Purpose & Scope
| Included | Excluded |
|---|---|
| One-step business onboarding (org + merchant + channels + access) | Employee lifecycle and login (→ User Management) |
| Organization profile, hierarchy, settings, attachments | Role/permission definition (→ Permissions) |
| Merchant creation (single, batch, aggregate) and profile | Product catalog content (→ Products) |
| Business-type classification (RETAIL / FNB / TICKET / OTHER) | Stock levels (→ Inventory) |
| Sale-channel management | Order / checkout processing (→ Orders) |
| Category management with add-on flag | Payment processing (→ Payment) |
| Per-merchant deletion policy | E-invoice issuance (→ Tax & Invoice) |
| Encrypted merchant configuration (payment/integration credentials) |
Organization vs Merchant. The Organization is the virtual brand layer (name, logo, public profile) and carries no legal identity. The Merchant is the physical/legal unit - it holds the tax number (MST), e-invoice profile, and wallet, and is where sales actually occur. Creating an Organization always auto-creates one default Merchant.
3. Capabilities
| Capability | What the user can do |
|---|---|
| Business onboarding | Create the whole structure (organization + default merchant + sale channels + owner access) in one step |
| Organization profile | Edit name (multilingual), slug, contact, address, social links, registration info |
| Organization hierarchy | Link a parent organization to child organizations |
| Organization settings | Store polymorphic key-value configuration on an organization |
| Merchant - single create | Add one merchant to an organization |
| Merchant - batch create | Add several merchants in one request |
| Merchant - aggregate create/update | Create or update a merchant with its categories and channels in one atomic operation |
| Business type | Set the POS interface type per merchant (RETAIL / FNB / TICKET / OTHER) |
| Deletion policy | Configure per-merchant cascade rules for category/product deletion |
| Merchant configuration | Store encrypted payment-provider and integration credentials |
| Sale channels | Manage channels via merchant aggregate; batch-add to existing merchant; hierarchy |
| Categories | Manage categories via merchant aggregate; mark as add-on |
| Status lifecycle | Activate / deactivate / archive organizations and merchants |
| Identifier lookup | Find an organization or merchant by ID or by slug |
| Role-based filtering | Owners see their own data; employees see only assigned merchants |
| Standalone channel/category CRUD | Manage channels/categories independently of the merchant aggregate |
| Ownership transfer | Reassign an organization to a different owner |
4. Module Dependencies
| Depends on | Why |
|---|---|
| User Management | The owner and employees belong to the organization / merchants |
| Permissions | Roles are scoped to organization or merchant; onboarding grants the owner access |
| Depended on by | Why |
|---|---|
| Products | Products are scoped to a merchant |
| Device | Devices are assigned to merchants |
| Orders | Sales occur per merchant and sale channel |
| Tax & Invoice | Tax info is captured on the merchant; invoice profiles are per merchant |
| Finance | Finance wallets are per merchant |
5. Backend Packages
Implementation detail lives in the developer docs - this section only maps the module to the service that powers it.
| Package | Role | Developer docs |
|---|---|---|
@nx/commerce | Organizers, merchants, onboarding, sale channels, categories, settings, devices, encrypted integrations; CDC source of truth | commerce |
Engineering Mapping (Feature ⇄ Package)
The horizontal axis of the Feature Spine - each business feature (
<AREA>in the URD) maps to its engineering home. Reciprocal: the package docs link back here.
| Feature | Dev package | Status |
|---|---|---|
ORG Organization | @nx/commerce | Built |
MER Merchant | @nx/commerce | Built |
SC Sale Channels | @nx/commerce | Built |
ACC Access | @nx/commerce | Built |
CAT Categories | @nx/commerce | Built |
DEL Deletion Policy | @nx/commerce | Built |
CFG Configuration | @nx/commerce | Built |
RCP Receipt Templates | @nx/commerce · @nx/core | Built |
FLR Table & Floor Allocation | @nx/commerce · @nx/sale · @nx/core | Built |
RTL Retail business type | @nx/commerce | Planned |
BOP Backoffice portal | @nx/commerce · @nx/helpdesk | Planned |
6. Key User Flows
Onboarding (atomic setup)
Aggregate merchant create/update (smart update)
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Owner | Onboard, create/update/deactivate/archive organization and merchants, manage channels/categories/settings, assign employees | Access other owners' organizations |
| Manager | Manage assigned merchants and their channels/categories (per granted scope) | Create organizations; manage merchants outside scope |
| Employee | View assigned merchants and their structure | Create or modify merchants; see unassigned merchants |
| Super Admin | Access all organizations and merchants (bypasses role filtering) | - |
8. Status & Roadmap
| Phase | Capabilities |
|---|---|
| P1 | Atomic onboarding (organization + default merchant + sale channels + owner access) |
| P2 | Full organization & merchant management: profiles, hierarchy, aggregate create/update, business types, deletion policy, encrypted configuration, role-based filtering |
| P3 | Planned: standalone channel/category CRUD, ownership transfer, cascade deactivation, company-wide setting defaults, MST validation, multi-brand support |
9. Related Pages
- URD
- PRDs
- Developer docs:
@nx/commerce - Related modules: User Management · Permissions · Products · Tax & Invoice