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.

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 (DEFAULT / TICKET / FNB / THEATER)	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	Status
Business onboarding	Create the whole structure (organization + default merchant + sale channels + owner access) in one step	Built
Organization profile	Edit name (multilingual), slug, contact, address, social links, registration info	Built
Organization hierarchy	Link a parent organization to child organizations	Built
Organization settings	Store polymorphic key-value configuration on an organization	Built
Merchant — single create	Add one merchant to an organization	Built
Merchant — batch create	Add several merchants in one request	Built
Merchant — aggregate create/update	Create or update a merchant with its categories and channels in one atomic operation	Built
Business type	Set the POS interface type per merchant (DEFAULT / TICKET / FNB / THEATER)	Built
Deletion policy	Configure per-merchant cascade rules for category/product deletion	Built
Merchant configuration	Store encrypted payment-provider and integration credentials	Built
Sale channels	Manage channels via merchant aggregate; batch-add to existing merchant; hierarchy	Built
Categories	Manage categories via merchant aggregate; mark as add-on	Built
Status lifecycle	Activate / deactivate / archive organizations and merchants	Built
Identifier lookup	Find an organization or merchant by ID or by slug	Built
Role-based filtering	Owners see their own data; employees see only assigned merchants	Built
Standalone channel/category CRUD	Manage channels/categories independently of the merchant aggregate	Planned
Ownership transfer	Reassign an organization to a different owner	Planned

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
Expenses	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

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
• Test Cases
• PRDs
• Developer docs: @nx/commerce
• Related modules: User Management · Permissions · Products · Tax & Invoice