Developer guide — Sales channels
How a backend module integrates with the Sales Channels module: scoping queries by the resolved channel, managing memberships, and reading channel context from request handlers.
Reading the resolved channel inside a route
The resolver middleware resolves the sales channel of every request under /api/v1/* and stores it (a CachedChannel view of the row) on the request's platform scope, not on the request object. Read it with the helpers the platform kernel publishes:
import { getResolvedChannel } from '@endora-commerce/platform/kernel';
app.get('/api/v1/storefront/products', async () => {
const channel = getResolvedChannel();
return productService.list({ salesChannelId: channel.id });
});
getResolvedChannel() throws (500) when the resolver did not run on the path; currentSalesChannel(), from the same barrel, returns null instead. Neither needs the FastifyRequest, so a service deep in the call chain can read the channel without having it threaded through. (getResolvedChannel still accepts a request argument for older call sites and ignores it.)
Outside the request lifecycle (background jobs, CLI scripts), resolve the salesChannelResolutionPort from the container and call getByCode(code) or getSystemDefault(); type it with SalesChannelResolutionPort from @endora-commerce/platform/kernel. The SalesChannelResolverService class behind it is not published.
Channel access: routes that must stay open
Every non-admin /api/v1/* request is checked against the channel-access rule after its channel is resolved: an anonymous request is accepted only on a channel open to anonymous visitors (403 SALES_CHANNEL_SIGN_IN_REQUIRED otherwise), a customer request only on a channel assigned to the customer's Organization (403 SALES_CHANNEL_NOT_PERMITTED otherwise). Administrator and API-key requests are not checked. A route of yours is therefore refused on a closed store unless it says otherwise.
A route whose caller is not a shopper of the store — or has to reach it to become one — declares that on the route:
app.post(
'/api/v1/payments/acme/notify',
{ config: { salesChannelAccess: 'open' } },
async (request, reply) => {
// Still resolved to a channel, and still behind this route's own guards.
},
);
Declare it on every provider callback your module receives — a payment gateway's notification, a carrier's status webhook, a return URL a provider redirects a browser to. Those requests arrive without a session and usually without a storefront channel, so they are anonymous requests on the system-default channel: the moment an operator closes that channel to anonymous visitors, an undeclared callback is refused with 403 and the provider's notifications stop arriving. The same applies to links in e-mails that must work for someone who is not signed in (confirmation, unsubscribe) and to anything a sign-in or registration form needs before the visitor has an account.
Do not declare it on anything that shows or changes a store's catalogue, prices, basket or orders: those are exactly what the rule protects. Individual (B2C) self-registration is deliberately not open, because it signs the visitor in at once.
'open' skips the access step only. The request is still resolved to a channel (an unknown or inactive channel is still refused), and the route's own guards — requireCustomer, requireAdmin, a signature check — still run. In this repository the set of open routes is held by backend/test/contract/sales_channels/channel-access-open-routes.test.ts against the ledger backend/test/helpers/channel-access-open-routes.ts, which gives a reason for each route; adding an open route means adding its ledger entry.
Checking the rule yourself
A path that creates a customer session outside the shared sign-in routes must refuse before it creates one. Resolve the salesChannelAccessPort from the container, typed with SalesChannelAccessPort from @endora-commerce/platform/kernel:
const { salesChannelAccessPort } = ctx.cradle<YourCradle>();
// Throws the 403 SALES_CHANNEL_NOT_PERMITTED refusal, with details.channelCode.
await salesChannelAccessPort.assertCustomerMayUse(account.organizationId, channel.id);
// Or read the decision, or the channels an Organization may use (cached).
const decision = await salesChannelAccessPort.decide(actor, channel);
const permitted = await salesChannelAccessPort.permittedChannelIds(organizationId);
The port is provided by the kernel; it needs no manifest dependency.
Where assignments live
The assignment is the channel's organization membership — the sales_channel_organizations bridge — written only through salesChannelMembershipPort, which also drops the access cache for the Organization before it reports the change. The per-customer record (sales_channel_customer_accounts) takes no part in access: it stays registered as a bridge and is neither read nor written by the rule. Grant access by assigning the customer's Organization, never by writing a per-customer row.
Adding a channel-scoped entity to your module
Channel scoping has two layers:
- Schema — the entity gains a many-to-many relationship to
sales_channelsvia a new bridge tablesales_channel_<entity>(composite primary key on both ids,ON DELETE CASCADEon both sides). Add the table in your module's next migration. - Service — every read path of the entity that should be filtered by channel takes a
salesChannelIdparameter and joins through the bridge table. Every create / update path that lands a new entity callsbindToDefaultIfEmpty(entityType, entity.id)on thesalesChannelMembershipPortafterpersistAndFlushso newly-created entities default to the system-default channel.
Then add the member to the contract's ChannelMemberEntityTypeSchema enum, and declare the bridge from your own module: export the { entityType, table, entityIdColumn } triple from src/backend/index.ts and register it from a boot hook —
ctx.onBoot(() => {
const { salesChannelBridgeRegistry } = ctx.cradle<YourCradle>();
for (const bridge of salesChannelBridges) salesChannelBridgeRegistry.register(bridge);
});
The bidirectional admin routes then pick it up automatically — no per-module routes needed. The platform deliberately holds no map of the bridges: it used to, total over the enum, which meant a membership call for a member whose module an instance never installed ran SQL against a relation that is not there. A member no module registered now refuses with 503 MODULE_DISABLED before the database is reached, and the enum stays the published vocabulary while the registry decides which members are live.
Mutating memberships
SalesChannelMembershipService is the single mutator for every bridge table. A module reaches it as the salesChannelMembershipPort container entry, typed with SalesChannelMembershipPort from @endora-commerce/platform/kernel; the class itself is not published. Direct INSERT / DELETE on sales_channel_* from anywhere else is forbidden, and check:module-boundary is what enforces it: it resolves every sales_channel_* table to its owner from the DDL and reports a module that writes one in raw SQL.
const result = await membershipService.addToChannel(channelId, 'product', productId);
// result.changed is false on idempotent re-add.
const removed = await membershipService.removeFromChannel(channelId, 'product', productId, {
fallbackToDefault: true,
});
// throws ENTITY_WOULD_HAVE_ZERO_CHANNELS if it would orphan the entity AND fallbackToDefault is false.
The Default channel guarantee
The DefaultChannelReconciler runs at every backend boot, from the platform's composition (packages/platform/src/composition/compose-app.ts), and therefore also in the integration-test server. Three branches:
- Empty
sales_channelstable — inserts a newdefaultrow sourced fromDEFAULT_SALES_CHANNEL_CODE(env, defaultdefault). - Rows exist but none has
system_default = true— promotes the lexically-first row, with a tie-break preferring the row whosecode = 'default'. - Exactly one row already has
system_default = true— no-op.
The reconciler never demotes, never deletes, and never edits identity. Code outside this module assumes the default exists; if you're writing infra-level code that runs before the reconciler, call DefaultChannelReconciler.run() first.
Optimistic concurrency for identity edits
The version integer column on sales_channels increments by exactly 1 on every successful identity update. The PATCH endpoint requires the client's expectedVersion to match the row's current version, mismatch → HTTP 412 STALE_SALES_CHANNEL_WRITE with the current version in the error envelope so the client can refresh and retry.
Membership add / remove operations are idempotent by construction and do not bump the channel's version.
Audit hooks
Every identity change, lifecycle change, and membership change writes one audit_log_entries row synchronously inside the same transaction. Action codes live in @endora-commerce/contracts:
import { SALES_CHANNEL_AUDIT_ACTIONS } from '@endora-commerce/contracts';
await auditLogService.record({
action: SALES_CHANNEL_AUDIT_ACTIONS.IDENTITY_CHANGED,
// ...
});
Use the constants — never hardcode the strings — so a future enum / type rename ripples cleanly.
Cache invalidation
SalesChannelsCache (process-local LRU + Redis) holds a CachedChannel per code. The cache is invalidated on every identity / lifecycle change via the existing EventBus:
sales_channels.identity_changed→ drops one entry by code.sales_channels.lifecycle_changed→ drops one entry, or all entries wheninvalidateAll: trueis set (used on hard delete).
Both drop the shared Redis entry first and the local one second, with the key marked for the whole operation so a concurrent read cannot re-pin the pre-change channel — and so a failed Redis drop leaves reads falling through to PostgreSQL rather than being served the value the invalidation was meant to remove. The EventBus is in-process, so a second instance converges through the local layer's 30 s window instead.
Membership lookups go through MikroORM directly (no cache layer); if you need them faster, add a Redis layer keyed by (entityType, entityId) with a short TTL — the hooks are already in place.
Contributing a panel to the channel edit page
The edit page of an existing channel mounts the admin zone sales_channel.editor.after below the
identity form, with the props { channelId, saveSession }. saveSession is the page's one Save
(issue #407, specs/180-one-save-zone-editors/): a panel that registers its staged changes with it
is counted by the form's Save and written after the channel, in zone order, and a panel that does
not keeps writing on its own — as inventory's warehouse routing does, under an Applies
immediately badge. The create form runs no session.
Storefront URLs and the language prefix
Every storefront page URL carries the language as its first segment. Never compose one by
hand — the derivation lives in @endora-commerce/contracts:
channelUrlLanguages(channel)/channelUrlLanguageAliases(channel)— the derived prefix of every channel language (and split aliases).channelis anyChannelUrlFacts(languages,defaultLanguage,prefixDefaultLanguage); the cached channel (getResolvedChannel(),SalesChannelResolutionPort) satisfies it.storefrontPagePath({ path, languageCode, channel })— a logical path (/c/tools,/verify?token=…) under the language's prefix; throws on a language the channel lacks.storefrontPagePathFor({ path, channel, requestedLanguage })— for messages: the requested language when the channel serves it, else the channel default; the logical path when no channel is known. Every e-mail, redirect or feed that links a storefront page goes through this orproductPath.productPath({ key, languageCode, channel })— a product page. It used to takechannelDefaultLanguageand append?lang=; it now takeschanneland never appends?lang=.productDefaultPath(key)is the unprefixedx-defaulttarget.
GET /api/v1/storefront/sales-channel answers prefixDefaultLanguage, urlLanguages and
urlLanguageAliases, so a headless storefront never re-derives them. The admin channel
shapes carry prefixDefaultLanguage; it is written by the audited identity Command.
Testing your channel-aware code
Use the existing setupBackendServer() test harness — it boots the full stack with a fresh default channel reconciled against the test seed (en-US / PLN). For raw-DB-level tests, use setupTestDb() and call DefaultChannelReconciler.run() yourself, optionally overriding the bootstrap defaults if your test seeds different language/currency codes.
The repo's existing precedent for channel-aware integration tests (transactional rollback, parameterised entity types, raw-SQL fixtures decoupled from owning-module entity classes) is in:
backend/test/integration/sales_channels/bidirectional-membership-every-bridge.test.ts— table-driven over all 9 bridges.backend/test/integration/sales_channels/at-least-one-channel-invariant.test.ts— enforcement of the at-least-one-channel invariant.backend/test/contract/sales_channels/admin-membership.contract.test.ts— HTTP-side cover.