Merchants, Marketplaces & Stores

Section 1

The shape of the platform

There is no Client model and no SubMerchant model. Every business on the platform — a direct merchant, a marketplace, a marketplace's sub-merchant — is a row in the same Merchant table, distinguished by tier and stitched into a tree by parentClientId. The tree is pure Ummah software: on Adyen's balance platform, every one of those rows is a fully independent legal entity with its own account holder, balance account and transfer instrument.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart LR
  subgraph UDB["Ummah database — the tree"]
    direction TB
    C["Merchant · tier CLIENT
isMarketplace true"]
    S1["Merchant · tier SUBMERCHANT"]
    S2["Merchant · tier SUBMERCHANT"]
    C -->|"parentClientId"| S1
    C -->|"parentClientId"| S2
  end
  subgraph ADY["Adyen balance platform — flat siblings"]
    direction TB
    A1["Legal entity · account holder
balance account · transfer instrument"]
    A2["Legal entity · account holder
balance account · transfer instrument"]
    A3["Legal entity · account holder
balance account · transfer instrument"]
  end
  C -.->|"adyen ids"| A1
  S1 -.->|"adyen ids"| A2
  S2 -.->|"adyen ids"| A3
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;
  class C client
  class S1,S2 sub
  class A1,A2,A3 adyen

prisma/schema.prisma:38-41 · prisma/schema.prisma:390-399 · prisma/schema.prisma:519-563 · src/modules/submerchant/submerchant.service.ts:44-55

Section 2

The vocabulary

Ten identifiers carry the whole model. All names below are verbatim from prisma/schema.prisma and the backend services.

prisma/schema.prisma:38-41 · prisma/schema.prisma:390-399 · prisma/schema.prisma:446-467 · prisma/schema.prisma:519-563

Section 3

Tiers, gates & the one-way lock

Two separate booleans govern marketplace behaviour, and they are checked by different doors. Understanding which flag gates which path explains most of the surprises in this feature.

Two flags, two doors

• isMarketplace is checked by SubMerchantService.inviteSubMerchant — the service behind both the staff door and the Client self-service door. A Client without it receives 403 client_not_marketplace. It is set either by staff via PATCH /api/admin/clients/:clientId/marketplace, or automatically: a successful first invite through the portal door flips it to true so marketplace-gated logic (sub lists, split configuration) recognises the Client.
• canCreateSubMerchants is checked by PortalSubMerchantsService.invite and by the portal sidebar. It is granted only on the admin invite form (the InviteMerchantDialog checkbox, which also opens the Ummah commission inputs — see Pricings, Splits & Fees).

A Client can therefore satisfy one gate but not the other — one of the documented gaps in Section 8.

The one-way lock

PATCH /api/admin/clients/:clientId/marketplace enforces two rules. Only tier === CLIENT rows may become marketplaces — anything else is refused with 400 not_a_client, which transitively blocks sub-of-sub through this path. And marketplace mode is one-way once used: disabling it while sub-merchants exist is refused with marketplace_locked (a deliberate product decision, recorded 2026-08-17).

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart TD
  REQ["PATCH /api/admin/clients/:clientId/marketplace"]
  DIR{"enable or disable?"}
  TIER{"tier is CLIENT?"}
  NC["400 not_a_client
blocks sub-of-sub too"]
  ON["isMarketplace = true"]
  HAS{"sub-merchants exist?"}
  LOCK["marketplace_locked
one-way once used"]
  OFF["isMarketplace = false"]
  REQ --> DIR
  DIR -->|"enable"| TIER
  TIER -->|"no"| NC
  TIER -->|"yes"| ON
  DIR -->|"disable"| HAS
  HAS -->|"yes"| LOCK
  HAS -->|"no"| OFF
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;
  class REQ ummah
  class DIR,TIER,HAS,OFF plain
  class NC,LOCK danger
  class ON client

No nesting — three separate guards

Sub-merchants cannot have sub-merchants, but no single invariant says so. Three guards in three places combine to enforce it:

• Portal tier check — PortalSubMerchantsService.invite returns 403 when the caller's tier === SUBMERCHANT ("Sub-merchants cannot invite further sub-merchants").
• Flag zeroing at creation — AdminMerchantsService.createInvite forces canCreateSubMerchants: false and subMerchantCommission* = 0 on any SUBMERCHANT row it creates.
• Toggle tier check — setMarketplaceMode only accepts CLIENT rows (400 not_a_client).

SubMerchantService.inviteSubMerchant itself never re-checks the target's tier — it relies transitively on isMarketplace only ever being settable on CLIENT rows. The invariant holds today, but it is distributed, not declared.

src/modules/submerchant/submerchant.service.ts:595-646 · src/modules/merchants/portal-submerchant.service.ts:43-123 · src/modules/admin/admin-merchants.service.ts:385-391 · prisma/schema.prisma:459-467

Section 4

Inviting a sub-merchant

Three routes create a SUBMERCHANT row. Two share a service; the third delegates to the admin invite machinery — and the difference decides whether the new sub arrives priced or unpriced.

4a · Three doors in

The assertSelf check on the Client door deserves a note: the controller compares the bearer token's merchantId to the path's :clientId and returns 403 not_your_marketplace on mismatch. All six handlers of ClientSubMerchantController call it, and sub-resources additionally re-verify ownership via getOwnedSub (matching id, parentClientId and tier: SUBMERCHANT). The doc comment records that the path parameter was previously trusted as-is — the fix is real, but it is a per-controller convention, not a shared guard (G5).

4b · Invite to ACTIVE

Whichever door created it, the sub-merchant then walks the same onboarding chain as a top-level Client: code entry, Sumsub WebSDK verification, then Adyen provisioning through the BullMQ queue. The full state machine and Sumsub detail live in Onboarding & KYC; the sequence below shows the sub-merchant-specific path end to end.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13px","primaryColor":"#FBE5D6","primaryTextColor":"#00273A","primaryBorderColor":"#E86C2B","lineColor":"#8195A1","actorBkg":"#FFFFFF","actorBorder":"#D2D8DE","actorTextColor":"#00273A","actorLineColor":"#D2D8DE","signalColor":"#33505F","signalTextColor":"#33505F","activationBkgColor":"#FBE5D6","activationBorderColor":"#E86C2B","noteBkgColor":"#FEF3DC","noteBorderColor":"#E8D5A8","noteTextColor":"#00273A","labelBoxBkgColor":"#F1F4F8","labelBoxBorderColor":"#D2D8DE","loopTextColor":"#33505F"},"sequence":{"mirrorActors":false,"actorMargin":46,"messageMargin":30,"boxMargin":8}}}%%
sequenceDiagram
  participant CL as Marketplace Client
  participant API as Ummah backend
  participant SUB as Sub-merchant owner
  participant SS as Sumsub
  participant Q as BullMQ worker
  participant AD as Adyen
  CL->>API: POST /api/clients/:clientId/submerchants/invites
  Note over API: assertSelf + isMarketplace gate
row created INVITED · audit submerchant.invited
  API-->>SUB: invite email · 6-digit code
  SUB->>API: POST /api/portal/onboarding/:id/open
  SUB->>API: POST /api/portal/onboarding/:id/verify
  Note over API: OPENED to VERIFIED · mints MERCHANT JWT
  SUB->>API: POST /api/portal/onboarding/:id/sumsub-token
  SUB->>SS: Sumsub WebSDK iframe · documents
  SS-->>API: POST /webhooks/sumsub · GREEN (HMAC-verified)
  API->>Q: job provisionMerchant · queue adyen-provisioning
  Q->>AD: legal entity · business line · ToS · account holder · balance account · transfer instrument
  AD-->>API: ACCOUNT_HOLDER.UPDATED · verificationStatus valid
  Note over API: markActive · ensureDefaultStore reuses onboarding BA

Resending is Client-controllable: POST /api/clients/:clientId/submerchants/:subId/resend-invite is allowed only from INVITED, RESUBMISSION_REQUESTED or EXPIRED, and revives an EXPIRED sub back to INVITED with a fresh code.

src/modules/submerchant/submerchant.controller.ts:52-285 · src/modules/submerchant/submerchant.service.ts:308-501 · src/modules/merchants/portal-submerchant.service.ts:43-123 · src/modules/onboarding/onboarding.controller.ts:46-201 · src/modules/onboarding/provisioning.service.ts:34-92 · src/core/queue/queue.constants.ts:5-44

Section 5

Stores as sales channels

A Store is where a merchant actually sells: a named channel with its own money boundary. The crucial design choice is that every store gets its own Adyen balance account, provisioned under the merchant's existing account holder — which means new channels need no additional KYC, and each channel's funds are separable.

Anatomy

• Identity — displayName, status (StoreStatus: ACTIVE or DISABLED), isDefault.
• Money boundary — its own adyenBalanceAccountId plus adyenTransferInstrumentId; the ringFenced flag disables cross-store recovery so this channel's losses stay its own.
• Acquiring surface — an Adyen Management-API store (adyenStoreId) with default payment methods visa, mc, maestro, amex, applepay and googlepay auto-requested per the merchant's business line.
• Pricing attachment — splitProfileId points at the split profile whose Adyen split configuration auto-divides every payment, with the remainder booked to this store's balance account. How the legs divide is the subject of Pricings, Splits & Fees.
• Legacy columns — mccOverride, pricingOverride, webhookConfig, apiKeyScope are explicitly marked "Do not build new code against these".

Lifecycle

The default store is created by StoresService.ensureDefaultStore when the merchant goes ACTIVE: it reuses the balance account already provisioned during onboarding (no second account), stamps merchant.defaultSplitProfileId onto the store, runs ensureAdyenStore to create the Management-API store and request payment methods, and finally applyPendingSplitProfile pushes the split configuration onto the Adyen store. Additional stores go through StoresService.create, which provisions a fresh balance account under the same account holder.

Who chooses the split is asymmetric by design. Per the StoresService.create comment, admins may choose one; merchants never do — only AdminStoresController passes { allowSplitProfile: true }, the portal store-create route ignores dto.splitProfileId entirely, and a merchant's new store inherits the default store's split.

%%{init:{"theme":"base","themeVariables":{"fontFamily":"Bricolage Grotesque, Inter, Segoe UI, sans-serif","fontSize":"13.5px","primaryColor":"#FFFFFF","primaryTextColor":"#00273A","primaryBorderColor":"#D2D8DE","lineColor":"#8195A1","secondaryColor":"#F1F4F8","tertiaryColor":"#F7F8FA","clusterBkg":"#F7F8FA","clusterBorder":"#E5E8EC","edgeLabelBackground":"#FFFFFF"},"flowchart":{"curve":"basis","nodeSpacing":36,"rankSpacing":48,"padding":10}}}%%
flowchart LR
  NEW["New store
StoresService.create"]
  DEF["Default store at activation
ensureDefaultStore"]
  BA["Own balance account provisioned
under the account holder · no extra KYC"]
  REU["Reuses the onboarding
balance account"]
  AST["ensureAdyenStore
adyenStoreId · payment methods
visa mc maestro amex applepay googlepay"]
  SPL{"splitProfileId?"}
  LIVE["Payments auto-split by the
attached configuration · remainder
to this store's balance account"]
  BLK["Checkout guard
blocks payments"]
  NEW --> BA
  DEF --> REU
  BA --> AST
  REU --> AST
  AST --> SPL
  SPL -->|"attached"| LIVE
  SPL -->|"none"| BLK
  classDef ummah fill:#FBE5D6,stroke:#E86C2B,stroke-width:1.5px,color:#00273A;
  classDef liable fill:#E86C2B,stroke:#B84E1F,stroke-width:1.5px,color:#FFFFFF;
  classDef adyen fill:#00273A,stroke:#00273A,color:#FFFFFF;
  classDef client fill:#E8F0FE,stroke:#1A73B8,stroke-width:1.5px,color:#00273A;
  classDef sub fill:#E6F4EA,stroke:#1E8E3E,stroke-width:1.5px,color:#00273A;
  classDef warn fill:#FEF3DC,stroke:#B26A00,stroke-width:1.5px,color:#00273A;
  classDef danger fill:#FCE8E6,stroke:#C5221F,stroke-width:1.5px,color:#00273A;
  classDef plain fill:#FFFFFF,stroke:#D2D8DE,stroke-width:1.5px,color:#00273A;
  class NEW plain
  class DEF ummah
  class BA,LIVE sub
  class REU plain
  class AST adyen
  class SPL plain
  class BLK danger

prisma/schema.prisma:519-563 · src/modules/stores/stores.service.ts:31-38 · src/modules/stores/stores.service.ts:90-117 · src/modules/stores/stores.service.ts:473-544 · src/modules/stores/stores.service.ts:611-655 · src/modules/checkout/payments.service.ts:257-261

Section 6

The screens

Two Next.js 15 apps operate this model. The merchant portal gives a marketplace Client day-to-day control of its subs; the backoffice gives Ummah staff the authoritative levers. Both share one light-only design language.

Merchant portal

The sidebar shows Sub-merchants and Splits only when merchant.canCreateSubMerchants is set and the tier is not SUBMERCHANT — capability granted at invite, not mere tier. A sub-merchant visiting /sub-merchants sees "Not available".

Backoffice

ummah-platform-merchant-portal/components/nav/Sidebar.tsx:129-154 · ummah-platform-merchant-portal/app/(app)/sub-merchants/page.tsx:32-90 · ummah-platform-merchant-portal/components/sub-merchants/InviteSubMerchantDialog.tsx:38-167 · ummah-platform-merchant-portal/app/(app)/sub-merchants/[id]/page.tsx:32-79 · ummah-platform-backoffice/app/(app)/merchants/[id]/page.tsx:108-133 · ummah-platform-backoffice/components/merchants/InviteMerchantDialog.tsx:36-123 · ummah-platform-backoffice/components/merchants/MerchantStoresTab.tsx:159-230

Section 7

Implementation notes

Endpoints

Adyen counterparts per row

Who may do what — roles in brief

Authorisation is JwtAuthGuard plus RolesGuard reading @RequireScope('STAFF'|'MERCHANT') and @RequirePermissions(...). A user's JWT scope is derived — any STAFF-scope role makes the token STAFF, otherwise MERCHANT — and system roles (StaffAdmin, MerchantOwner) store no permissions, resolving to allPermissions(scope) at token time from the registry. Fine-grained names (sub-merchants.view, stores.create, team.delete) are flattened through a bridge marked TEMPORARY onto the coarse decorator names (merchant.read, merchant.write) that the hierarchy controllers actually check — and the bridge has holes (G4). @CurrentMerchant() resolves the acting merchant from the API key or the JWT and 403s staff tokens, keeping staff and merchant surfaces cleanly apart.

src/modules/submerchant/submerchant.controller.ts:52-285 · src/modules/auth/permissions.registry.ts:37-179 · src/modules/auth/roles.guard.ts:11-50 · src/modules/auth/auth.service.ts:72-158 · src/common/decorators/current-merchant.decorator.ts · prisma/schema.prisma:342-345 · prisma/schema.prisma:483-563 · prisma/schema.prisma:621-623

Section 8

Gaps & recommendations

Everything below was verified in code. Priorities: p0 blocks money or correctness, p1 is commercial or operational friction, p2 is polish.