Billing, entitlements & messaging

This complete shared-module example defines a monthly organization plan and the feature it grants. It uses the same SharedSaaSModule.productDefinitions registration as Wonder Todos. Merge these contributions into your existing shared engine module; do not replace its other features, roles or products. The example identifiers and offer are application-owned.

import {
  defineFeature, ProductType, ResourcePrimaryScope,
  type ProductDefinition, type SharedSaaSModule,
} from '@wildo-ai/saas-models';
import { BillingInterval, PricingModel } from '@wildo-ai/external-connectors-models';
import { AvailableCurrency } from '@wildo-ai/zod-decorators';

export enum CommercialFeature { REPORTS = 'advanced-reports' }

export const professional: ProductDefinition = {
  key: 'professional',
  type: ProductType.PLAN,
  targetScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  grantedFeatures: [CommercialFeature.REPORTS],
  planTier: 'professional',
  planTierOrder: 1,
  prices: [{
    model: PricingModel.FLAT,
    unitPrice: { amount: 2900n, decimals: 2, currency: AvailableCurrency.USD },
    interval: BillingInterval.MONTH,
    intervalCount: 1,
    isDefault: true,
  }],
};

const engineModule: SharedSaaSModule = {
  moduleId: 'engine',
  kind: 'engine',
  customFeatureDefinitions: [
    defineFeature(CommercialFeature.REPORTS, { scope: ResourcePrimaryScope.ORGANIZATIONS }),
  ],
  productDefinitions: [professional],
};
export default engineModule;

2900n with two decimals means USD 29, not USD 2,900 or USD 0.29. A yearly alternative belongs in the same product’s prices array with BillingInterval.YEAR; it does not need another product or another grant. Keep the product key stable: subscription items and provider mappings use it. Author the offer’s customer-facing labels in the application’s billing labels/specifications.

The module must participate in the application’s assembled shared modules. A declaration in an unimported file does nothing. See billing setup for capability, provider and environment prerequisites.

Check the synchronized offer before selling it

Catalogue synchronization materializes separate Product and Price records and establishes provider mappings. A complete syncProductCatalog() pass reports synchronization errors; on-demand synchronization also supports checkout. A compiled declaration alone is not proof that the provider accepted the price.

The grant feeds effective entitlements. Protect the report operation with that feature requirement; displaying a plan name does not authorize a report. Follow feature grants for the consuming check.

Retire an offer without rewriting history

A complete sync retires locally stored products absent from the authored catalogue and disables their local prices. It retains the records and reports live subscribers; it does not migrate those subscribers or archive their provider prices. Existing renewal history remains resolvable while new acquisition rejects the retired offer. Provider retirement and customer migration remain deliberate operational decisions.

This is the professional plan’s monthly price from Wonder Todos. It is a selected member of the product’s prices array:

The following selected excerpt is from product.ts; the surrounding module and explanatory source comments are omitted.

model: PricingModel.FLAT,
unitPrice: { amount: 2900n, decimals: 2, currency: AvailableCurrency.USD },
interval: BillingInterval.MONTH,
intervalCount: 1,
isDefault: true,

amount: 2900n with decimals: 2 means 29.00 USD. The integer is not the display amount. The yearly alternative uses 29000n and BillingInterval.YEAR. Resolve a price belonging to the selected product; checkout rejects mismatched product/price pairs.

A recurring price combines interval with intervalCount: MONTH with 3 bills every three months; an omitted count defaults to 1. Catalog sync preserves that cadence in the local price and the provider request. A one-time price has no recurring interval. Existing provider-linked prices are not automatically rewritten when a declaration changes.

Match the model to provider behavior

The price schema describes flat, per-unit, tiered, graduated and package models. Tier rows carry an upper bound and unit/flat amounts; an open-ended final bound uses null. Metered consumption still needs the application to record usage. Declaring a per-unit price does not measure activity.

The sync service converts every amount from its authored scale into the currency’s minor units before calling the provider. It rejects an amount that cannot be represented exactly rather than rounding the charge. For example, a sub-cent authored USD amount cannot be treated as a whole cent merely because its integer is 1n. Inspect synchronization errors and use a representable commercial unit.

Each price carries its own currency. Global defaultCurrency and supportedCurrencies record commercial intent but do not validate or rewrite price currencies. Changing a stored price also requires confirming the provider price mapping and the treatment of existing subscribers; provider-linked prices are not a promise that every later edit creates a replacement provider price.

Wonder Todos’ professional plan contains the following policy. These are selected fields from shared-lib/src/engine/product.ts:

The following selected excerpt is from product.ts; the surrounding module and explanatory source comments are omitted.

behaviorPolicy: {
  trial: { days: 14, requirePaymentMethod: false },
  upgrade: { proration: ProrationBehavior.CREATE_PRORATIONS, timing: BillingTiming.IMMEDIATE },
  downgrade: { proration: ProrationBehavior.NONE, timing: BillingTiming.AT_PERIOD_END },
  cancellation: { allowImmediate: false, defaultBehavior: BillingTiming.AT_PERIOD_END },
},

Trial days come from the product policy, falling back to the application default. Checkout callers cannot override them; a product value of zero disables the trial. requirePaymentMethod is passed to hosted checkout when starting a trial. Cancellation resolves caller preference, product default and application default, then refuses any effective immediate cancellation forbidden by the product. An authored immediate default requires allowImmediate: true; contradictory product policies fail validation. An explicit period-end choice still overrides an immediate default.

Distinguish adjustment from scheduling

The target product’s tier order distinguishes an upgrade from a downgrade. An application should not tell a customer that a downgrade is scheduled merely because timing says period-end: a scheduled change needs a provider scheduling mechanism. Keep the commercial wording consistent with the actions offered. Other product-policy fields, such as metering declarations, also require their corresponding usage implementation rather than executing by declaration alone.

This complete configuration example authors two inputs for an existing billing setup: the backend tax settings and a tax-exclusive monthly price. Merge taxSettings into billing.tax, and use monthlyPrice in the registered product’s prices array. Provider selection, SDK, secrets and catalogue registration are covered in billing setup and the product catalogue.

import {
  TaxCalculationMode, TaxDisplayMode, type BillingConfiguration, type PriceDefinition,
} from '@wildo-ai/saas-models';
import { BillingInterval, PricingModel } from '@wildo-ai/external-connectors-models';
import { AvailableCurrency } from '@wildo-ai/zod-decorators';

export const taxSettings: NonNullable<BillingConfiguration['tax']> = {
  calculationMode: TaxCalculationMode.PROVIDER_MANAGED,
  defaultDisplayMode: TaxDisplayMode.EXCLUSIVE,
};

export const monthlyPrice: PriceDefinition = {
  model: PricingModel.FLAT,
  unitPrice: { amount: 2900n, decimals: 2, currency: AvailableCurrency.USD },
  interval: BillingInterval.MONTH,
  intervalCount: 1,
  isDefault: true,
  taxBehavior: TaxDisplayMode.EXCLUSIVE,
};

The first input makes hosted checkout request provider-managed tax calculation; Stripe receives automatic_tax.enabled. The price’s taxBehavior is sent when the price is created at the provider. USD 29 is the base price in this example; the resulting tax depends on the provider’s configured tax service and customer details.

Verify each owner’s result

Calculation and display are different controls. Disabling automatic calculation does not make a price tax-inclusive. The current catalogue sync passes the price-level value directly: there is no fallback from an unset price to product.taxDisplayMode or billing.tax.defaultDisplayMode. Author taxBehavior explicitly on each price. A global display setting does not rewrite customer-facing labels or already-created provider prices.

Use a provider test purchase to inspect the final session and invoice, rather than treating a compiled configuration as proof of a tax result. The framework delegates calculation; the provider account configuration remains an application operator responsibility.

Enable EngineCapability.BILLING in wildo.saas.config.ts. In the backend configuration, set billing.enabled, select providerRef and declare enabledScopes. Organization billing and personal billing are distinct resource families; enable the scopes the commercial model actually uses.

Wonder Todos authors this backend provider scope in wildo.saas.config.ts. The surrounding providers.scopes.backend.providers object is omitted:

The following selected excerpt is from wildo.saas.config.ts; the surrounding module and explanatory source comments are omitted.

stripe: {
            engineCapabilities: [EngineCapability.BILLING],
            providerCapabilities: ['BILLING'],
            protocols: ['BILLING_PROVIDER', 'WEBHOOK_ORIGINATOR'],
          },

BILLING_PROVIDER supplies outgoing billing operations; WEBHOOK_ORIGINATOR registers incoming events. A frontend Stripe SDK entry alone cannot supply either backend responsibility. Engine-shipped providers are discovered from their package: do not add a second manual provider contribution.

Finish the deployment chain

Startup resolves the configured provider and required secrets. A missing provider scope is a configuration failure, not a reason to silently disable charging. Once initialized, the frontend’s billing context loads the selected customer’s account through the scoped billing resource. The application authors its products and commercial terms separately from these connection settings.

StandardBilling_Interface is the backend adapter contract. The runtime resolves the billing provider from the authored backend scope and gives billing services that interface. Stripe is the shipped implementation; a different vendor needs a complete adapter, an SDK-package entry in the engine billing adapter registry and provider registration, not just a different providerRef string.

The Stripe implementation’s update path shows the boundary. The complete method below maps metadata, proration and subscription items:

The following selected excerpt is from stripe-standard-billing-provider.backend.service.ts; the surrounding module and explanatory source comments are omitted.

async updateSubscription(providerSubscriptionId: string, request: StandardBilling_UpdateSubscriptionRequest): Promise<void> {
    await this.getStripe().subscriptions.update(providerSubscriptionId, {
      metadata: request.metadata,
      ...(request.prorationBehavior && { proration_behavior: request.prorationBehavior }),
      ...(request.providerPromotionCodeId && { promotion_code: request.providerPromotionCodeId }),
      ...(request.items && {
        items: request.items.map((item) => ({
          ...(item.providerSubscriptionItemId ? { id: item.providerSubscriptionItemId } : {}),
          price: item.providerPriceId,
          quantity: item.quantity,
        })),
      }),
    });
  }

The application chooses the product and policy. The billing operation constructs StandardBilling_UpdateSubscriptionRequest; the adapter names the provider’s fields. A contract field only has an effect when that adapter implements its meaning.

What a new provider must connect

Use the mock billing provider for application tests that need deterministic billing responses. Such tests exercise application behavior; they do not establish that a live vendor accepts every translated request. Switching an existing deployment also requires deciding how its provider customer, price and subscription identifiers migrate.

Select stripe as the billing provider, enable billing, author the backend provider scope and install stripe in backend-api/package.json. The adapter loads the SDK on the backend. Keep its API secret and webhook signing secret in the environment’s provider configuration, regenerate with wildo config sync, and connect the webhook endpoint.

The adapter converts the shared checkout contract into a Stripe session. The complete createCheckoutSession method shows customer, prices, redirect destinations, tax and trial mapping:

The following selected excerpt is from stripe-standard-billing-provider.backend.service.ts; the surrounding module and explanatory source comments are omitted.

async createCheckoutSession(request: StandardBilling_CreateCheckoutSessionRequest): Promise<StandardBilling_CreateCheckoutSessionResponse> {
    const session = await this.getStripe().checkout.sessions.create({
      customer: request.providerCustomerId,
      line_items: request.lineItems.map((item) => ({ price: item.providerPriceId, quantity: item.quantity ?? 1 })),
      mode: request.mode,
      success_url: request.successUrl,
      cancel_url: request.cancelUrl,
      metadata: request.metadata,
      ...(request.allowPromotionCodes && { allow_promotion_codes: true }),
      ...(request.providerPromotionCodeId && { discounts: [{ promotion_code: request.providerPromotionCodeId }] }),
      ...(request.automaticTax && { automatic_tax: { enabled: true } }),
      ...(request.requirePaymentMethodForTrial && { payment_method_collection: 'always' as const }),
      ...(request.trialPeriodDays
        ? {
          subscription_data: {
            trial_period_days: request.trialPeriodDays,
            ...(request.requirePaymentMethodForTrial
              ? { trial_settings: { end_behavior: { missing_payment_method: 'cancel' as const } } }
              : {}),
          },
        }
        : {}),
    });
    return { url: session.url!, sessionId: session.id };
  }

The method composes trial settings and returns the session URL and ID. Use the application’s useBilling().openCheckout(...) action or standard billing components to reach it through the authorized resource operation; do not expose the SDK secret to a browser.

Keep provider configuration explicit

The adapter also supplies customer-portal sessions, subscription updates, cancellation, usage reporting and promotion operations. Those are connected contracts, not permission to assume every Stripe product is exposed by Wildo. Webhook verification uses the provider’s signing secret; event delivery must reach the application for local state to follow payment activity. Test keys and live keys belong to their corresponding deployment environments. Configure the provider’s own portal and payment behavior before offering them to customers.

Reuse prices only when their terms match

When a local price has no provider link, catalog synchronization can reuse an active Stripe price only when its commercial terms match: currency, amount or tiers, billing cadence, package size and tax behavior. A quarterly price is distinct from a monthly price, and graduated tiers are distinct from volume pricing. Missing tier or currency detail prevents reuse, and extra currency offers are treated as a different price; metadata alone never proves equality. Existing linked prices continue through their established synchronization path.

Enable the intended billing.enabledScopes: organization billing uses the organization variant; personal billing uses USER_SELF. The standard billing context resolves the active organization first when that scope is enabled, otherwise the current personal scope when available. Your purchase interface should make that payer clear.

The state service finds or creates the scope’s account. Creation uses the ordinary internal operation with the scope in execution context, so the registered provider-customer creation handler also runs:

The following selected excerpt is from billing-state.backend.service.ts; the surrounding module and explanatory source comments are omitted.

const scopeContext: { organizationId?: string; userId?: string } =
  variants.scopeEntityDocField === 'userId'
    ? { userId: scopeEntityId }
    : { organizationId: scopeEntityId };
const created = await this.systemAccessService.createAsSystem<BillingAccount>(
  variants.billingAccount as CoreResourceType,
  {},
  { scopeContext },
);
return created ?? null;

The creation handler asks the provider for a customer, then stores providerCustomerId, providerRef and the local account. Application code should use this flow rather than manufacture a row or copy a provider ID from another scope.

Use the resulting account

GET_STATE returns the account alongside its billing view. OPEN_CHECKOUT and OPEN_PORTAL address that account through scoped resource operations. Both require its provider customer mapping; a local row without a provider customer is not ready to purchase.

This account is a financial anchor, not a payment card record. Hosted payment details stay with the provider. Account retention also differs from deleting a workspace: retained financial children and their provider references must remain connected.

This complete teaching component mounts inside the application’s existing BillingProvider. Supply the stable product key and a translated button label. It selects that product’s active default price, distinguishes unavailable state and handles action failure. The surrounding application owns routing, translations and visual components; plain HTML keeps the purchase contract visible here.

import { useState } from 'react';
import { useBilling } from '@wildo-ai/saas-frontend-lib';
import { BillingStateSlice } from '@wildo-ai/saas-models';

export function PurchaseOffer({ productKey, label }: { productKey: string; label: string }) {
  const billing = useBilling();
  const [busy, setBusy] = useState(false);
  const [failed, setFailed] = useState(false);
  if (!billing.isEnabled) return <p>Billing is not available.</p>;
  if (billing.isLoading) return <p>Loading billing…</p>;
  if (billing.error) return <button onClick={billing.refetch}>Reload billing</button>;
  const ready = [BillingStateSlice.BILLING_ACCOUNT, BillingStateSlice.SUBSCRIPTION,
    BillingStateSlice.PRODUCTS, BillingStateSlice.PRICES].every(billing.isSliceAvailable);
  if (!ready) return <button onClick={billing.refetch}>Offer unavailable — retry</button>;

  const product = billing.getProductByKey(productKey);
  const eligible = product && product.isActive !== false && billing.currentScope
    && product.targetScopes.includes(billing.currentScope);
  const price = product && billing.getPricesForProduct(product._id)
    .find(candidate => candidate.isActive !== false && candidate.isDefault);
  if (!eligible || !price || !billing.billingAccount) return <p>This offer is unavailable.</p>;
  const selectedProduct = product;
  const selectedPrice = price;
  const hasSubscription = billing.subscription !== null;

  async function purchase() {
    if (busy) return;
    setBusy(true);
    setFailed(false);
    try {
      if (hasSubscription) await billing.openCustomerPortal();
      else await billing.openCheckout(selectedProduct.key, selectedPrice._id);
    } catch {
      setFailed(true);
    } finally {
      setBusy(false);
    }
  }
  return <div>
    <button disabled={busy} onClick={purchase}>{hasSubscription ? 'Manage subscription' : label}</button>
    {failed && <p role="alert">The billing provider could not be opened. Please try again.</p>}
  </div>;
}

The highlighted selection binds the price to its product. The action uses the current scoped billing account; it does not accept an arbitrary organization ID from the button. This example chooses the portal when a subscription exists, matching the standard plan-selection behavior. A dedicated add-on or one-time-purchase screen should use its own explicit purchase action instead of that plan-management branch.

For a public catalogue, additionally filter visibility using isPublic. A private active offer can be intentionally offered through a direct selection: public visibility is not backend purchase authorization. See the shared billing view for the complete distinction.

Keep request validation on the server

The authorized account operation rejects a retired product, a product aimed at another scope and a price belonging to another product. Optional quantity and promotion code belong in openCheckout’s third argument. Trial duration comes from product/application policy on the server. Reserved checkout metadata is constructed there; caller metadata cannot replace its account, product or quantity.

The context supplies return destinations and navigates to the returned provider URL. It ignores a concurrent second invocation while checkout is opening. A rejected request reaches the component’s catch path; do not silently swallow it or retry a purchase automatically.

Show the purchase result, not just a successful redirect

Opening checkout produces a session, not an active subscription. The customer can abandon it. Signed provider events reconcile the account’s subscription and purchase result, and scoped billing events refresh the context. On the return screen, show the current subscription/loading/unavailable state and allow refresh while processing completes. Effective feature access is read through the separate feature context, not inferred from the return URL.

One-time products use the same registered catalogue, scoped account and openCheckout action as plans. Product type selects the checkout mode: PLAN, ADDON and METERED use subscription mode; ONE_TIME, ITEM and CREDIT_PACK use payment mode. An absent price interval describes a non-recurring price.

This complete catalogue entry sells a pack of report credits. Add it to the shared module’s productDefinitions alongside the rest of the catalogue. The identifiers and amounts are an illustrative application offer.

import { ProductType, ResourcePrimaryScope, type ProductDefinition } from '@wildo-ai/saas-models';
import { PricingModel } from '@wildo-ai/external-connectors-models';
import { AvailableCurrency } from '@wildo-ai/zod-decorators';

export const reportCredits: ProductDefinition = {
  key: 'report-credits',
  type: ProductType.CREDIT_PACK,
  targetScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  purchaseConfig: {
    creditsPerUnit: 10,
    creditPoolKey: 'reports',
    maxQuantityPerPurchase: 5,
  },
  prices: [{
    model: PricingModel.FLAT,
    unitPrice: { amount: 1000n, decimals: 2, currency: AvailableCurrency.USD },
    intervalCount: 1,
    isDefault: true,
  }],
};

Resolve the synchronized product by report-credits and its own active price from useBilling(), then call openCheckout(product.key, price._id, { quantity: 2 }). Use the same loading, availability and error handling shown in hosted checkout, but call checkout directly for this pack even if a plan subscription already exists. The example’s two units cost USD 20 before any tax or promotion and correspond to twenty report credits.

Let confirmed payment produce the result

The signed checkout completion path resolves the trusted account and product, validates settlement and deduplicates delivery. For CREDIT_PACK with a creditPoolKey, it computes creditsPerUnit × quantity and tops up that scoped pool. The billing credit view can then show the recorded balance; a checkout redirect alone must not increment it.

Credit consumption is separate from purchasing: connect the operation that generates a report to the credit pool mechanism. Calling an item “a report” does not install report generation or delivery.

Keep provider selection on the billing path

Enable EngineCapability.BILLING and configure its provider. There is no independently selectable payment-provider contract; the retired BILLING_PAYMENTS name is not an alternative vendor slot. One-time checkout uses the billing provider already connected to this account.

Use the scoped subscription operations, not a generic update of status or items. This complete teaching hook exposes the five actions independently. Mount its consumer under the normal resource registry and BillingProvider, passing the active organization, its billing account ID and subscription ID. Resolve the account from available useBilling().billingAccount state before mounting the consumer. Backend authorization still decides whether this person may mutate that subscription.

import { useState } from 'react';
import { useBilling, useResourceRegistry } from '@wildo-ai/saas-frontend-lib';
import {
  BillingSubscription_Operations, CoreResourceType, DataMode, ResourceOperationVariantType,
  BillingSubscription_CancelRequestDto, BillingSubscription_ChangePlanRequestDto,
  BillingSubscription_AddAddonRequestDto, BillingSubscription_RemoveAddonRequestDto,
  type BillingSubscriptionBase,
} from '@wildo-ai/saas-models';

type SubscriptionResult = Pick<BillingSubscriptionBase,
  '_id' | 'status' | 'cancelAtPeriodEnd' | 'currentPeriodEnd'>;

export function useOrganizationSubscription(organizationId: string, organizationBillingAccountId: string, organizationSubscriptionId: string) {
  const { doOperation } = useResourceRegistry();
  const billing = useBilling();
  const [busy, setBusy] = useState(false);
  const [failed, setFailed] = useState(false);
  const [result, setResult] = useState<SubscriptionResult | null>(null);
  async function run(operationIdentifier: BillingSubscription_Operations, request: () => Record<string, unknown>) {
    setBusy(true); setFailed(false); setResult(null);
    try {
      const updated = await doOperation<SubscriptionResult>({
        resourceIdentifier: CoreResourceType.ORGANIZATION_SUBSCRIPTIONS,
        operationIdentifier,
        variantType: ResourceOperationVariantType.API_CALL,
        isOperationDefault: true,
      }, {
        contextualParameters: { organizationId, organizationBillingAccountId, organizationSubscriptionId },
        requestData: request(),
        dataMode: DataMode.RAW,
      });
      setResult(updated);
      billing.refetch();
    } catch { setFailed(true); }
    finally { setBusy(false); }
  }
  return {
    busy, failed, result,
    cancel: () => run(BillingSubscription_Operations.CANCEL,
      () => BillingSubscription_CancelRequestDto.parse({ cancelImmediately: false })),
    resume: () => run(BillingSubscription_Operations.RESUME, () => ({})),
    changePlan: (newProductKey: string, newPriceId: string) => run(BillingSubscription_Operations.CHANGE_PLAN,
      () => BillingSubscription_ChangePlanRequestDto.parse({ newProductKey, newPriceId })),
    addAddon: (addonProductKey: string, priceId: string) => run(BillingSubscription_Operations.ADD_ADDON,
      () => BillingSubscription_AddAddonRequestDto.parse({ addonProductKey, priceId })),
    removeAddon: (addonProductKey: string) => run(BillingSubscription_Operations.REMOVE_ADDON,
      () => BillingSubscription_RemoveAddonRequestDto.parse({ addonProductKey })),
  };
}

export function CancelAtRenewal({ organizationId, billingAccountId, subscriptionId }: { organizationId: string; billingAccountId: string; subscriptionId: string }) {
  const action = useOrganizationSubscription(organizationId, billingAccountId, subscriptionId);
  return <section>
    <button disabled={action.busy} onClick={action.cancel}>Cancel at renewal</button>
    {action.failed && <p role="alert">Cancellation failed. Check the current subscription before trying again.</p>}
    {action.result && <p>{action.result.cancelAtPeriodEnd
      ? 'Cancellation is scheduled at period end.' : 'Subscription updated.'}</p>}
  </section>;
}

The result type is a projection of public fields used by this screen, not the complete backend record. Mount the example with a key derived from organization, billing account and subscription IDs to reset local feedback when the active customer changes. Only show actions after the subscription slice is available. Customer-facing labels here are illustrative; the application supplies translated wording and its confirmation interaction.

The example requests period-end cancellation explicitly. An omitted timing uses product/application policy. An immediate request forbidden by the product is refused, not silently changed to period end. The result reports the updated subscription; it does not assert that every asynchronous entitlement consumer has already refreshed.

Choose one action and inspect its result

These are alternatives initiated by separate user decisions, not a sequence to run together. The request schemas validate each payload. Resolve selected products and their own prices through the billing context before calling changePlan or addAddon; provider price_… identifiers are not the local price IDs expected here. For personal subscriptions use USER_SUBSCRIPTIONS and { userId, userBillingAccountId, userSubscriptionId }.

Let provider events complete the picture

Webhook handling reconciles status and billing-period bounds. The billing context refetches on relevant scoped events. The browser returning from checkout is not evidence that the subscription has become active.

Plan change validates the new product and price, preserves the intended plan/add-on distinction and sends proration to the provider. A declared period-end plan-change timing is not a subscription schedule in the current Stripe adapter. Use the policy guide when designing changes; cancellation timing and plan-change scheduling are different contracts.

Remove an add-on without changing the other items

For example, removing extra storage should leave the plan and a seats add-on intact. Invoke REMOVE_ADDON with the storage product’s addonProductKey. The handler requires an add-on product (a plan key is refused), resolves it even if retired, locates its subscription entries and requires their recorded provider item IDs. A missing ID refuses the operation before provider mutation; it never guesses from the position of an item.

After those checks, the handler sends explicit deletions and returns the surviving local items:

const provider = getBillingProvider();
await provider.updateSubscription(subscription.providerSubscriptionId, {
  removedProviderSubscriptionItemIds,
});

return { items: remainingItems };

The Stripe adapter translates those IDs into items: [{ id, deleted: true }]. Unmentioned items remain unchanged at the provider. Only after that call succeeds does the resource operation persist the remaining local entries. This is a provider update, not a request to replace the entire remote item list.

Keep existing subscription item identities

Plan changes preserve the known provider item ID. Changing a plan or adding an add-on requires every existing item to have its provider item ID recorded; otherwise the operation refuses before contacting the provider. This prevents an existing line from being mistaken for a new purchase.

A new line carries a backend-generated correlation key. The provider returns its created item ID under that key, and the operation records it immediately with the local line. Consecutive changes therefore keep targeting the same provider items without waiting for a webhook. Missing identities in older records still require an explicit repair; routine status reconciliation does not repair item identities. Neither price nor array position is used to guess an ID.

useBilling().openCustomerPortal() calls the scoped account’s OPEN_PORTAL operation and follows its returned URL. Render the action after billing state has loaded and the correct payer is selected. The account must already have a provider customer ID.

The backend operation uses the current authorized account, not a caller-supplied provider customer:

The following selected excerpt is from billing-account.mutations.custom-impl.backend.service.ts; the surrounding module and explanatory source comments are omitted.

const result = await provider.createCustomerPortalSession(
  billingAccount.providerCustomerId,
  input.returnUrl,
);
return { url: result.url };

The surrounding handler checks that the provider customer exists. The Stripe adapter creates a portal session with that customer and the application’s return URL. Configure which portal features the provider offers; opening a session does not author those settings.

Keep invoice documents behind their intended access path

The local invoice list carries status and totals, while hosted invoice and PDF URLs are backend-only fields. Use the portal for customer access to provider billing documents rather than projecting those links into a generic response.

Changes performed at the provider can arrive through billing webhooks. Refresh local billing state when the customer returns, and keep application subscription actions aligned with the provider portal options you enable. A portal is a provider-managed surface, not a second independently implemented payment settings screen.

Enable the billing provider on the backend with both BILLING_PROVIDER and WEBHOOK_ORIGINATOR. Supply the provider signing secret and run wildo config sync. The provider module registers POST /api/v1/webhooks/stripe/billing; configure the provider or a local event forwarder to reach it. Keep the raw request body available for signature verification.

The billing adapter verifies the request through the selected provider implementation:

The following selected excerpt is from billing-webhook-adapter.backend.service.ts; the surrounding module and explanatory source comments are omitted.

verifySignature(
  rawBody: string | Buffer,
  signatureHeader: string,
  secret: string,
): boolean {
  return this.billingProvider.verifyWebhookSignature(
    typeof rawBody === 'string' ? rawBody : rawBody.toString('utf-8'),
    signatureHeader,
    secret,
  );
}

After verification, the adapter normalizes the event and retains its native event type and payload for scope resolution. The Stripe module matches data.object.customer against the account’s providerCustomerId across the enabled billing variants. A browser-supplied organization ID is not that authority.

Let each event perform its own work

Subscription events reconcile status and period bounds; invoice events upsert totals and status. Checkout completion checks reserved metadata against the resolved account before granting products or credits. The settlement path uses a persisted claim keyed by completion identity to avoid granting the same purchase again; it refuses a grant without a deduplication identity.

Do not translate that into a promise that every arbitrary side effect is exactly-once. Custom work must preserve its own failure and replay semantics. Provider-only fields are written through the trusted backend update path, so identifiers needed by subsequent events survive schema filtering. Inspect event delivery and the resulting resource state when integrating: reaching the endpoint is not proof that a purchase was reconciled.

useBilling().invoices contains the most recent fifty references. Check isSliceAvailable(BillingStateSlice.INVOICES) before interpreting an empty list. For a longer history, use the invoice resource’s scoped LIST operation.

This complete teaching component loads one page for an organization the caller is authorized to access. Mount it with a key derived from organization and billing account IDs when changing customers, so page state resets. The response type projects only fields used here; it does not claim that backend-only provider identifiers or hosted document URLs are public DTO fields. The application owns translations, amount formatting and visual components.

import { useEffect, useState } from 'react';
import { useResourceRegistry } from '@wildo-ai/saas-frontend-lib';
import {
  CoreResourceType, CoreResourceOperation, ResourceOperationVariantType, DataMode,
  type InvoiceRef, type Resources_PaginatedResult,
} from '@wildo-ai/saas-models';

type InvoiceRow = Pick<InvoiceRef, '_id' | 'status' | 'total' | 'createdAt'>;
type InvoicePage = Resources_PaginatedResult<InvoiceRow>;

export function OrganizationInvoiceHistory({ organizationId, organizationBillingAccountId }: { organizationId: string; organizationBillingAccountId: string }) {
  const { doOperation } = useResourceRegistry();
  const [page, setPage] = useState(1);
  const [retry, setRetry] = useState(0);
  const [result, setResult] = useState<InvoicePage | null>(null);
  const [loading, setLoading] = useState(true);
  const [failed, setFailed] = useState(false);
  useEffect(() => {
    let current = true;
    setLoading(true);
    setFailed(false);
    setResult(null);
    doOperation<InvoicePage>({
      resourceIdentifier: CoreResourceType.ORGANIZATION_INVOICE_REFS,
      operationIdentifier: CoreResourceOperation.LIST,
      variantType: ResourceOperationVariantType.API_CALL,
      isOperationDefault: true,
    }, {
      contextualParameters: { organizationId, organizationBillingAccountId },
      queryParameters: { page, limit: 20, sort: 'createdAt:desc' },
      dataMode: DataMode.RAW,
    }).then(value => { if (current) setResult(value); })
      .catch(() => { if (current) setFailed(true); })
      .finally(() => { if (current) setLoading(false); });
    return () => { current = false; };
  }, [doOperation, organizationId, organizationBillingAccountId, page, retry]);

  if (loading) return <p>Loading invoices…</p>;
  if (failed || !result) return <button onClick={() => setRetry(value => value + 1)}>Reload invoices</button>;
  return <section>
    <p>Page {page} — {result.pagination.total} invoices</p>
    <ul>{result.data.map(invoice => <li key={invoice._id}>
      {invoice._id}: {invoice.status}
    </li>)}</ul>
    {result.data.length === 0 && <p>No invoices on this page.</p>}
    <button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button>
    <button disabled={page >= result.pagination.totalPages}
      onClick={() => setPage(value => value + 1)}>Next</button>
  </section>;
}

The route is derived from the registered operation, with organization and billing-account context kept separate from pagination. Read the account ID from available useBilling().billingAccount state; do not render the history component until that account exists. The backend checks authorization; the component does not grant access by knowing an ID. For personal billing use USER_INVOICE_REFS with userId and userBillingAccountId, under that scope’s permissions. LIST is the browser API surface; the invoice resource’s internal SEARCH operation is not a replacement browser endpoint.

Preserve the meaning of the invoice

Finalized, paid and payment-failed provider events upsert invoice references for the resolved billing account. total remains the invoice total even when payment is outstanding; it is not replaced with the amount collected so far. Format its money value through the application’s normal money presentation and translate status using its registered labels.

The loading and error branches above distinguish “not read” from “no invoices.” The returned pagination metadata decides whether another page exists; a short aggregate or a locally filtered list is not a complete accounting history.

Open documents through the customer portal

Hosted invoice/PDF locations remain backend-only and are removed during subject erasure. Use useBilling().openCustomerPortal() for customer document access, with the same action error feedback as hosted checkout. Financial references can survive customer closure without exposing the original personal document to every API consumer.

Use useBilling() inside BillingProvider; use useBillingSafe() for a component that can appear without billing. The provider resolves the active payer and calls the scoped account’s GET_STATE operation. A successfully checked, absent account can be created through the billing account service path. A failed account lookup never counts as absence and does not trigger account creation.

Separate displayed offers from held products

The aggregate can retain a retired product because the customer’s subscription still references it. Its backend acquirableProductKeys distinguishes active purchase candidates, but the current useBilling() interface does not expose that field. For custom UI, use the supported context projection below: the returned products, their activity/visibility/scope fields and currentPlanProduct. The backend still validates every attempted purchase.

This complete component deliberately shows keys for inspecting the contract. A customer-facing screen should resolve product names from the application’s billing labels.

import { useBilling } from '@wildo-ai/saas-frontend-lib';
import { BillingStateSlice } from '@wildo-ai/saas-models';

export function OfferProjection() {
  const billing = useBilling();
  if (billing.isLoading) return <p>Loading offers…</p>;
  if (billing.error) return <button onClick={billing.refetch}>Reload billing</button>;
  if (!billing.isSliceAvailable(BillingStateSlice.PRODUCTS) || !billing.currentScope) {
    return <button onClick={billing.refetch}>Offers unavailable — retry</button>;
  }
  const scope = billing.currentScope;
  const candidates = billing.products.filter(product =>
    product.isActive !== false && product.targetScopes.includes(scope));
  const publicOffers = candidates.filter(product => product.isPublic);
  const subscriptionKnown = billing.isSliceAvailable(BillingStateSlice.SUBSCRIPTION);
  const heldPlan = subscriptionKnown ? billing.currentPlanProduct : null;

  return <section>
    <h3>Public purchase candidates</h3>
    <ul>{publicOffers.map(product => <li key={product.key}>{product.key}</li>)}</ul>
    {publicOffers.length === 0 && <p>No public offer in this scope.</p>}
    {!subscriptionKnown ? <p>Current subscription unavailable.</p>
      : <p>Current plan: {heldPlan?.key ?? billing.currentPlanKey ?? 'No plan'}</p>}
  </section>;
}

isActive !== false follows the server’s acquisition predicate, including its treatment of an absent activity value. The public listing adds its own visibility filter. Do not label a product “free” because prices failed to load: read the price slice before interpreting its contents.

Distinguish empty from unavailable

A successful response includes availability for the billing account, subscription, products, prices, invoices, usage, credit pools and active promotions. AVAILABLE means the read succeeded: an empty invoice list really means no invoices were returned. UNAVAILABLE means the slice could not be established; its empty fallback is not evidence that the customer has no invoices, no subscription or no remaining credits.

Use isSliceAvailable(BillingStateSlice.INVOICES) from the billing context before interpreting an invoice list. Keep healthy sections visible, show an unavailable state for the affected section, and offer refetch. Do not replace the whole billing screen with an error when other slices remain usable.

Availability also follows dependencies. When the subscription cannot be read, usage is unavailable because its billing period is unknown. When products cannot be read, active promotions are unavailable because eligibility depends on the catalogue. Per-slice responses contain availability states, not underlying storage errors; request-wide failures still use the normal error path.

Keep loading and updates visible

The context exposes isLoading, error and refetch, clears previous state when scope changes and listens for billing events belonging to the active account and scope. Standard components consume it; a custom screen should use the same loading/error state and refresh action.

Invoices are limited to the latest fifty in this aggregate. Usage appears only when the application records it. Credits and promotions are their own recorded systems, not estimates derived from the plan label. The aggregate is a convenient read model, while authorization, purchase validation and entitlement enforcement remain backend responsibilities.

Application billing uses organization and user variants for accounts, subscriptions, invoices, usage and credits. The frontend chooses the current payer; resource authorization checks the request. Do not replace those operations with an unscoped repository lookup from a browser-supplied ID.

The state service adds a scope check before its internal reads:

The following selected excerpt is from billing-state.backend.service.ts; the surrounding module and explanatory source comments are omitted.

const principalScopeId = (executionContext as unknown as Record<string, unknown> | undefined)?.[variants.scopeKey];
if (principalScopeId !== undefined && principalScopeId !== null && String(principalScopeId) !== String(scopeEntityId)) {
  throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
    context: {
      message: 'billing getState scopeEntityId does not match the authenticated principal scope',
      scopeType,
    },
  });
}
const billingAccount = await this.resolveOrCreateBillingAccount(variants, scopeEntityId);

A bound authenticated scope must match the requested scope entity. System/internal contexts without a bound scope can perform legitimate cross-account work; this check does not claim those trusted operations are tenant-restricted.

Check event identity independently of its signature

The provider module binds incoming events through data.object.customer and the local providerCustomerId. Checkout metadata is compared with that authoritative account; it does not choose the owner. Checkout also validates product scope and product/price binding before creating a provider session.

These checks cover distinct paths: a signed webhook proves origin, resource scope authorizes a human request, and the provider-customer mapping identifies the financial owner. The application must retain those paths when adding custom billing operations. A new direct repository or provider call needs its own explicit authorization and account resolution.

The core relationship registry disables parent-delete cascades for billing accounts and financial child families. The invoice scope relationship is one example:

The following selected excerpt is from resources-registry.shared.core.definitions.ts; the surrounding module and explanatory source comments are omitted.

...createPolymorphicScopeRelationships(invoiceRefsPolymorphicDeclaration, {
    nature: RelationshipNature.COMPOSITION,
    childOperations: { lifecycle: { onParentDelete: { enabled: false } } }, // RETAIN (compliance decision 2026-07-29) — see the billing-retention note above.
}),

The same policy connects each variant’s account to its financial children. These records are retained rather than moved behind a generic hidden/frozen resource state, because accounting still needs ordinary access to them.

Do not delete the financial anchor directly

The billing account’s internal delete handler checks subscriptions, invoice references, usage records and credit pools before allowing deletion. It requires a single addressed account and refuses deletion while dependents exist. A bulk address cannot bypass the scan by failing to name a particular account.

Use the normal scope lifecycle and subject-erasure operations, not a direct repository purge. Personal-data erasure and financial retention have different effects: the person’s identifying data can be treated while financial amounts and relationships remain. Provider-side erasure also keeps the provider customer identity resolvable for retained records.

The application still determines its applicable retention obligations and operating procedures. This mechanism preserves the declared financial relationships; it does not choose a universal legal retention duration or imply that every custom table has the same treatment.

Backend startup registers the billing effect when the relevant billing services are available. It resolves billing accounts for the subject and delegates through the configured billing provider. This actual effect fragment shows the ordered actions and the complete-result boundary:

Source: billing-subject-erasure-effect.backend.ts (selected excerpt).

        await cancelSubscriptions(provider, dependencies, variants, account._id, steps);
        await anonymizeCustomer(provider, providerCustomerId, steps);
        await detachPaymentMethods(provider, providerCustomerId, steps);
      }

      const failed = steps.filter((step) => !step.succeeded);
      if (failed.length === 0) {
        return {
          effectRef: BILLING_SUBJECT_ERASURE_EFFECT_REF,
          status: SubjectErasureExternalEffectStatus.COMPLETED,
          detail:
            `Provider-side erasure completed for ${accounts.length} billing account(s): subscriptions cancelled, `
            + `customer anonymized, payment methods detached. The customer record was KEPT (anonymized) so the `
            + `retained invoices remain attributable.`,
          steps,
        };
      }

The effect never calls deleteCustomer. Retaining the provider customer keeps invoice attribution intact; the provider implementation scrubs the supported personal customer fields instead. An absent billing account produces NOTHING_TO_ERASE. An unsynced local account contributes a successful skip-unsynced-billing-account step; the overall result still reflects the other accounts and steps.

The effect applies to USERS and USER_SELF and checks that user billing is registered before reading accounts. It selects the user-scoped billing variant; an employee account is not a reason to cancel an organisation’s shared subscription. Application builders should verify their billing subject ownership before extending the effect.

Each action records its own outcome. A failed provider step produces a partial receipt after local erasure, with details for provider-side follow-up. Verify provider state independently when completing the operational request. Financial retention purposes and periods are operator decisions; this mechanism preserves the relationship needed to implement them.

Start with one registered meaning

This example follows Wonder Todos’ ApplicationFeature.ADVANCED_REPORTS. Its identifier and definition live in shared-lib/src/engine/features.ts; the engine shared module registers the definitions as customFeatureDefinitions. This selected definition assigns organization scope and a member-specific response:

defineFeature(ApplicationFeature.ADVANCED_REPORTS, {
  scope: ResourcePrimaryScope.ORGANIZATIONS,
  unavailability: {
    behavior: FeatureUnavailabilityBehavior.UPGRADE_PROMPT,
    byRole: { [CORE_ORG_ROLES.ORG_MEMBER]: FeatureUnavailabilityBehavior.CONTACT_ADMIN },
  },
}),

The definition establishes what the feature means; it does not grant it. The enum and definition are exported through @wonder-todos/shared-lib. The builder, scope and policy enums come from @wildo-ai/saas-models.

Grant the same identifier from an offer

The existing Professional product grants advanced reports together with bulk export and custom workflows. This selected grant block belongs to ORG_PLAN_PROFESSIONAL in the application’s product.ts:

key: 'org-professional',
type: ProductType.PLAN,
targetScopes: [ResourcePrimaryScope.ORGANIZATIONS],

grantedFeatures: [
  ApplicationFeature.BULK_EXPORT,
  ApplicationFeature.ADVANCED_REPORTS,
  ApplicationFeature.CUSTOM_WORKFLOWS,
],

The complete registered product also contains prices, plan ordering and lifecycle policy. Its catalogue is contributed through the shared module’s productDefinitions. After the subscription is synchronized, billing-derived grants enter that organization’s entitlement ledger. The product catalogue covers product authoring; the feature identifier stays the same across offers.

Require it on the operation variant

Illustrative application configuration: a normal organization-scoped report resource uses this complete READ operation entry. It reuses the real feature identifier; it is not a claim that Wonder Todos already ships this report resource. Add the entry under operations[CoreResourceOperation.READ] in the registered report resource:

import {
  CORE_ORG_ROLES,
  CoreResourceOperation,
  ResourceOperationRiskLevel,
  ResourceOperationVariantType,
  type OperationConfig_ForKey,
} from '@wildo-ai/saas-models';
import { ApplicationFeature } from '@wonder-todos/shared-lib';

export const reportRead: OperationConfig_ForKey<CoreResourceOperation.READ> = {
  variants: [{
    variantType: ResourceOperationVariantType.API_CALL,
    isDefault: true,
    riskLevel: ResourceOperationRiskLevel.LOW,
    roles: [CORE_ORG_ROLES.ORG_MEMBER],
    requiredFeatures: [ApplicationFeature.ADVANCED_REPORTS],
  }],
};

requiredFeatures belongs on the variant, alongside its access rules. The surrounding resource supplies schema, organization scope and normal READ behavior. The request must satisfy both resource authorization and the feature gate. The product does not insert this requirement for you.

The interface guide uses the same identifier with FeatureGate. The expected comparison is explicit: without an effective grant, the protected user request is refused; with the grant and ordinary read permission, it can proceed. Test the endpoint directly as well as its screen.

Choose the right kind of number

FEATURES_UNLIMITED wins for an allowance but yields to a finite ceiling. Billing product grant aggregation and scope resolution are separate steps: do not assume every number simply adds together.

Put enforcement on the operation

Attach requiredFeatures to the protected operation variant, with explicit limitChecks where required. Boolean requirements support any-of or all-of checks; numeric checks count through the contextual repository and compare usage plus the operation’s increment with the allowance. A counting failure refuses the check.

The operation gate deliberately bypasses public execution, internal execution, repository-only/internal variants and system resources. Custom controllers can call checkRequiredFeatures; paid behavior on a bypassed path needs an explicit owning check. Frontend feature prompts explain availability; they do not secure the backend.

Resolve the effective set

Resolution layers definition defaults, the configured default profile when billing is disabled, subscription-derived grants and local manual overrides, then combines applicable scopes and prunes unmet dependencies. An override wins within its scope; a broader-scope grant can still participate in the merged context. Test both the purchased feature and its actual protected action, including the refusal case. An absent numeric limit is permissive, so registration is part of correctness.

Distinguish an absent entitlement record from a read failure

A successfully read, absent scope record uses the normal definition/profile defaults. A failed entitlement read does not: resolution fails, the protected action cannot obtain a successful entitlement decision, and no default grant is cached for the failed scope. This prevents a finite purchased ceiling from becoming unlimited during an outage, or a paid feature from being cached as unavailable.

A valid warm cache continues to serve its known result within the normal cache lifetime. After a cache-miss read recovers, the next resolution reads the ledger again. Broader-scope grants and limits still participate in normal composition; they do not turn a failed narrower-scope read into a successful decision.

The organisation has a scoped ORGANIZATION_FEATURES record. Billing synchronisation writes its features and limits; discretionary changes belong in manualOverrides. Keep those sources separate instead of editing a computed plan grant as if it were permanent.

The actual request contracts for the named administrator actions are:

export const OrganizationFeaturesEnableFeatureRequestDtoSchema = z.object({
  featureId: z.enum(CoreFeature),
  reason: z.string().max(500).optional()
});

export const OrganizationFeaturesDisableFeatureRequestDtoSchema = z.object({
  featureId: z.enum(CoreFeature),
  reason: z.string().min(1).max(500)
});

export const OrganizationFeaturesResetFeaturesRequestDtoSchema = z.object({
  reason: z.string().min(1).max(500)
});

These selected exports show that the enable/disable verbs accept CoreFeature identifiers. They are not a generic custom-feature endpoint. For an application-defined feature or a numeric exception, use the authorised resource update contract to write the appropriate override fields, through the normal resource operation pipeline. Its shared UPDATE hook already schedules resolution-cache invalidation.

Choose the change deliberately

The named verbs persist the override and invalidate the organization’s cached resolution. Ordinary authorized UPDATE has its own shared postfix hook, registered by the engine; it also schedules invalidation. You do not need to call a named enable/disable verb merely to obtain that hook.

Distinguish an administrative update from a storage repair

Application example: add the registered ADVANCED_REPORTS feature to an existing customer’s agreement. This helper runs inside an authorized super-administrator workflow, with the original external context and a server-resolved organisation identifier. It reads the current override block, changes only the intended feature, and writes through the resource pipeline:

import {
  CoreResourceType, type ScopeFeaturesWithOverrides,
} from '@wildo-ai/saas-models';
import type {
  ExecutionContext, ServicesRegistryHandlerBackendService,
} from '@wildo-ai/saas-backend-lib';
import { ApplicationFeature } from '@wonder-todos/shared-lib';

export async function grantReportingException(
  services: ServicesRegistryHandlerBackendService,
  context: ExecutionContext<any>,
  organizationId: string,
): Promise<ScopeFeaturesWithOverrides | null> {
  const resource = CoreResourceType.ORGANIZATION_FEATURES;
  const owner = { organizationId };
  const current = await services.read<ScopeFeaturesWithOverrides>(resource, context, owner);
  if (!current) throw new Error('Provision the customer entitlement record first');

  const featureId = ApplicationFeature.ADVANCED_REPORTS;
  const overrides = current.manualOverrides;
  return services.update<ScopeFeaturesWithOverrides>(resource, context, owner, {
    manualOverrides: {
      ...overrides,
      addedFeatures: [...new Set([...overrides.addedFeatures, featureId])],
      removedFeatures: overrides.removedFeatures.filter(id => id !== featureId),
      limitOverrides: { ...overrides.limitOverrides },
    },
  });
}

The feature import is from the Wonder Todos reference application; another application imports its own registered feature identifier. The named core-only enable/disable DTOs cannot express this application feature. The helper preserves unrelated exceptions from the record it read and removes a contradictory denial of reporting. It does not overwrite the subscription-owned base features or limits.

Read followed by UPDATE is not a compare-and-swap: simultaneous administrators could overwrite each other’s changes. Use this example for a controlled administrative workflow, not as a claim of concurrent edit protection. A rejected update or a null result is not a successful grant; the caller must handle it before displaying success. Record the agreement through the application’s administrative evidence flow.

The generic hook launches FeatureResolutionBackendService.invalidateCache(ResourcePrimaryScope.ORGANIZATIONS, organizationId) without awaiting it and logs failures. A successful UPDATE response is not a promise that every cached consumer is already fresh. Inspect both the stored record and a subsequent effective resolution; do not diagnose the saved override from a screen that still holds an earlier result.

For this example, with no other scope grants: the base features array can remain unchanged while manualOverrides.addedFeatures gains ADVANCED_REPORTS; the refreshed effective feature set then includes reporting. A later billing refresh can replace base grants while retaining the override. Removing this exception restores the base decision—it does not force a denial if a plan or another applicable scope still grants reports.

Preserve the authority boundary

Organisation members can read/search the ledger under its contextual routes. All writes require APP_ADMIN_SUPER_ADMIN, including generic update; an organisation owner cannot promote themselves into a more expensive entitlement. The entitlement fields are marked as audit evidence, allowing the normal resource audit machinery to retain their before/after values.

Manual overrides do not expire automatically. If an agreement is temporary, the application operator must arrange its removal. The request’s reason field is not itself proof that a durable reason record exists; use the application’s verified administrative record for agreement history. The effective context also includes applicable broader-scope grants, so a local removal is not a universal deny across every scope.

For authenticated external requests, FeatureResolutionBackendService.resolve starts at application scope and adds organisation and user scopes available in the execution context. resolveForScope instead resolves one identified owner. The distinction matters for a feature such as outgoing webhook delivery that must be enabled independently for each owner.

Application example: decide whether an already-authorized organisation may deliver outgoing webhooks. The application’s backend receives the resolver through its service dependencies and derives organizationId from the authorized owner of the work, never from an unchecked request field:

import { CoreFeature, ResourcePrimaryScope } from '@wildo-ai/saas-models';
import type { FeatureResolutionBackendService } from '@wildo-ai/saas-backend-lib';

export async function mayDeliverOrganizationWebhook(
  featureResolution: FeatureResolutionBackendService,
  organizationId: string,
): Promise<boolean> {
  if (!organizationId) {
    throw new Error('An authorized organization is required');
  }
  return featureResolution.isFeatureEnabledAtScope(
    CoreFeature.M2M_WEBHOOK_DELIVERY,
    ResourcePrimaryScope.ORGANIZATIONS,
    organizationId,
  );
}

This is a complete illustrative gate helper, not a webhook sender or an authorization endpoint. Its caller must await it before dispatch: false stops delivery, and a resolution error must also stop delivery. Checking a non-empty identifier does not establish membership or authority; that must already have been established by the calling workflow.

Exact scope still includes that scope’s defaults, applicable no-billing profile, stored grants and overrides. It does not mean “read only the manual override.” For a feature applicable to users, use ResourcePrimaryScope.USERS with the authorized user ID; for an application owner, use APPLICATION with the application ID. Do not substitute a membership ID for a user ID. The webhook feature above applies to applications and organisations, not users.

For ordinary request-wide features, retain the original authenticated external execution context when calling resolve or isFeatureEnabled. Internally initiated contexts deliberately bypass the normal feature chain; creating one to check a customer’s access would answer the wrong question. Public execution uses application defaults rather than a signed-in customer’s entitlement chain.

Make applicability explicit

Features declare applicableScopes. A user-scoped feature does not become an organisation feature merely because a user is a member. M2M_WEBHOOK_DELIVERY explicitly declares scopeBoundary: true; callers must use isFeatureEnabledAtScope. Calling the general isFeatureEnabled helper for such a definition throws rather than silently inheriting an application grant.

There is no application-scope billing account rail: an application-level allowance cannot arrive from an application subscription. Use an applicable profile when billing is disabled or an operator override.

Keep roles and commercial access separate

A feature grant does not confer an administrator role, membership or permission to another customer’s records. User and organisation ledgers permit their configured scoped reads but reserve writes for the application super-administrator. Resolve the feature and run the operation’s ordinary access checks; both must fit the use case.

A profile is a no-billing deployment choice, not an extra subscription tier layered on top of billing. Switching billing on stops applying the configured profile, so migrate its intended grants into products or explicit overrides.

The resource contains a grant source plus a separate override object. The resolver combines those with defaults, applicable profiles and other scopes. A stored row therefore does not by itself describe every feature available in a request.

Application example: an authorized administrative view shows the stored organisation agreement beside its effective scope result. The context and organisation identifier must refer to the same authorized customer. Keep the external context when using the resource service so its read policy remains in force:

import {
  CoreResourceType, ResourcePrimaryScope,
  type ScopeFeaturesWithOverrides,
} from '@wildo-ai/saas-models';
import type {
  ExecutionContext, FeatureResolutionBackendService,
  ServicesRegistryHandlerBackendService,
} from '@wildo-ai/saas-backend-lib';

export async function inspectOrganizationAccess(
  services: ServicesRegistryHandlerBackendService,
  featureResolution: FeatureResolutionBackendService,
  context: ExecutionContext<any>,
  organizationId: string,
) {
  const stored = await services.read<ScopeFeaturesWithOverrides>(
    CoreResourceType.ORGANIZATION_FEATURES, context, { organizationId },
  );
  const effective = await featureResolution.resolveForScope(
    ResourcePrimaryScope.ORGANIZATIONS, organizationId,
  );

  return {
    stored,
    effective,
    sourceRecordExists: stored !== null,
  };
}

The explicit filter selects the owner’s record; it is not a replacement for authorization. This helper neither grants access nor refreshes caches. The resolver may return its cached scope result. After an administrative change, distinguish a fresh resolution from a previously cached result.

Illustrative before/after, assuming reporting has no default, profile or other grant:

removedFeatures and limitOverrides live beside addedFeatures in manualOverrides. An absent row is a legitimate result and can still resolve defaults or an applicable profile; a failed read is an error, not an empty agreement. Neither the ledger nor this inspection helper contains an automatic expiration schedule for exceptions.

The effective result above belongs to one organisation. resolve(context) answers the different question of effective access across the request’s applicable application, organisation and user layers. Use the appropriate result when explaining a protected action.

Use the resource that owns the agreement

Resource relationships determine the contextual address. Use generated resource operations and their actual context rather than inventing an unscoped /features mutation. Generic updates are powerful administration operations because the override fields must remain writable to the operator; tenant users cannot use that authority.

Preserve both producers

Billing sync owns the subscription-derived features and limits. Named enable/disable/reset operations own their specific override mutations and invalidate the affected scope cache. A bespoke administrator that edits records directly must also handle cache freshness through an authorised backend flow.

For verification, read the record after a subscription change, check that its manual exceptions remain, then inspect the resolver’s effective result and exercise a protected action. A successful database write alone proves neither fresh resolution nor backend enforcement. Keep direct storage repair separate from normal administrative operations so it cannot silently bypass these effects.

Define availability and the response to its absence

Wonder Todos defines product features in its shared configuration. This selected declaration gives advanced reports a default upgrade prompt and a member-specific response:

defineFeature(ApplicationFeature.ADVANCED_REPORTS, {
  scope: ResourcePrimaryScope.ORGANIZATIONS,
  unavailability: {
    behavior: FeatureUnavailabilityBehavior.UPGRADE_PROMPT,
    byRole: { [CORE_ORG_ROLES.ORG_MEMBER]: FeatureUnavailabilityBehavior.CONTACT_ADMIN },
  },
}),

The feature registry and the current scope’s grants determine availability. The policy determines how unavailability is presented. Product plans or non-billing feature profiles supply grants; the policy alone does not enable a feature.

Apply it at the surface that owns access

For an authored component, FeatureGate accepts a featureId and children. Its implementation renders those children when available, renders nothing for HIDE, otherwise delegates to a custom renderer or the policy-driven prompt. Use renderUnavailable only when the product needs a distinct presentation of the same availability result.

This complete illustrative component consumes the same ApplicationFeature.ADVANCED_REPORTS used by the Professional grant and protected READ variant. Place it in the normal application provider tree; its parent supplies the report content:

import type { ReactNode } from 'react';
import { FeatureGate } from '@wildo-ai/saas-frontend-lib';
import { ApplicationFeature } from '@wonder-todos/shared-lib';

export function ReportsAccess({ children }: { children: ReactNode }) {
  return (
    <FeatureGate featureId={ApplicationFeature.ADVANCED_REPORTS}>
      {children}
    </FeatureGate>
  );
}

When the effective grant is available, the report content renders. Once an unavailable result is resolved, the existing policy can offer an upgrade to an administrator or direct a member to their administrator. A HIDE policy renders nothing, including when a custom unavailable renderer exists.

The frontend treats unresolved/loading feature state optimistically to avoid flashing a lock. It must not be used to keep confidential data out of a response: the protected backend READ remains the authority. Keep data fetching on that authorized path even when the wrapper is already visible.

Resource operation variants and registered views can declare requiredFeatures. The route guard checks those requirements when the route is opened directly; action resolution applies the relevant policy to operation affordances. A manually hidden navigation item is not a replacement for either check.

Separate entitlement, permissions and installed capability

Test a direct route as well as its launcher. Also test billing-disabled and non-administrator cases: an upgrade prompt without a usable action is not helpful guidance.

AppPage_BillingSettings is a Settings Hub panel composing SubscriptionStatus, BillingPortalLink, PricingTable, UsageDashboard and InvoiceHistory. Each widget reads the shared billing context; the panel does not fetch every billing child resource independently.

This selected part of the actual engine panel shows the plan, usage and invoice sections. Label resolution and earlier subscription/management sections are omitted:

<Card>
  <CardHeader>
    <CardTitle>{t('plansHeading')}</CardTitle>
  </CardHeader>
  <CardContent>
    {/* Self-hydrates: public active PLAN products scoped to the current
        billing scope; select = checkout (no subscription) / portal (active). */}
    <PricingTable />
  </CardContent>
</Card>

<Card>
  <CardHeader>
    <CardTitle>{t('usageHeading')}</CardTitle>
  </CardHeader>
  <CardContent>
    <UsageDashboard />
  </CardContent>
</Card>

<Card>
  <CardHeader>
    <CardTitle>{t('invoicesHeading')}</CardTitle>
  </CardHeader>
  <CardContent>
    <InvoiceHistory />
  </CardContent>
</Card>

The aggregated state is important: subscription and invoice resources are contextual children of the billing account. A generic organisation-level resource panel cannot simply invent their parent URLs.

Connect the commercial configuration before the screen

Enable billing for the application, register its product catalogue, and select the provider in the backend provider scope. Configure its credentials and webhook/runtime integration, then run wildo config sync to regenerate the application artifacts.

For an engine-shipped provider, selecting its reference in providers.scopes.backend.providers is sufficient for discovery: do not create a duplicate provider module or provider-contributions.ts entry. An authored contribution is needed when the application itself supplies a provider module. Backend billing still needs its matching providerRef, and the relevant SDK dependency must be installed. The frontend’s BillingContext reads the resulting state. Plan selection chooses the available checkout or portal action according to that state and the current subscription.

The Settings Hub then places the engine billing destination in an appropriate category. The destination is capability-gated; placement alone does not configure billing or grant a person billing-management rights.

Recompose widgets when the product needs another layout

The shared widgets can be used in an authored surface without replicating their data and action plumbing. Keep their billing provider/context available and retain their unavailable/loading behavior. The application still owns prices, entitlements, metering meaning and the customer-facing wording that explains those choices.

CoreFeature names entitlements. EngineCapability controls engine availability; it is not automatically converted into a sellable feature. Applications add their own definitions through customFeatureDefinitions on a shared module and use product grants to package both sets.

These two actual engine definitions show independent commercial identifiers:

{
  identifier: CoreFeature.SINGLE_SIGN_ON,
  valueType: FeatureValueType.BOOLEAN,
  applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  dependencies: [],
  defaultValue: false,
},
{
  identifier: CoreFeature.AUDIT_LOGS,
  valueType: FeatureValueType.BOOLEAN,
  applicableScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  dependencies: [],
  defaultValue: false,
},

The excerpt is from core-feature-definitions.shared.ts. Both are organisation-scoped booleans with a false default. Enabling one does not imply the other. Read the feature’s actual consumer before presenting it as an automatic complete product: a definition with no attached check does not enforce anything by its existence.

Combine built-in and application features deliberately

A product can package the same advanced-reporting feature from the definition-to-operation example alongside the built-in sign-on entitlement. This complete typed grant list is an illustrative extension of an existing organization offer, not the current Wonder Todos Enterprise package:

import { CoreFeature, type ProductDefinition } from '@wildo-ai/saas-models';
import { ApplicationFeature } from '@wonder-todos/shared-lib';

export const organizationOfferFeatures: NonNullable<ProductDefinition['grantedFeatures']> = [
  ApplicationFeature.ADVANCED_REPORTS,
  CoreFeature.SINGLE_SIGN_ON,
];

Assign the list to that offer’s grantedFeatures, retaining its targetScopes, prices and lifecycle settings. Keep the application definition registered; do not redeclare CoreFeature.SINGLE_SIGN_ON, which already has an engine definition. A published product grant still needs the subscription/ledger synchronization path before it affects a customer.

The two features have different consumers. Reports require the authored operation variant and FeatureGate shown in the linked guides. The built-in SSO settings destination declares entitlementFeatureId: CoreFeature.SINGLE_SIGN_ON, organizational management roles and runtime availability, then opens the registered SSO resources. That is a concrete settings consumer; it does not prove every SSO backend path is commercially gated. Enterprise settings gates and customer integration configuration explain those separate responsibilities.

Keep deployment, purchase and setup distinct

Settings destinations combine runtime availability, roles and entitlement IDs. The underlying services retain their own required setup. A customer does not get a working identity-provider connection simply because a plan contains SINGLE_SIGN_ON.

Verify the particular feature you sell

Core numeric definitions such as member/API-key allowances describe counting resources but are not automatically installed as create checks by core registration. An application that sells an enforced cap must wire its operation check. This differs from custom defineLimitFeature declarations using countResource.

Keep a specification beside custom definitions so application tooling can explain their meaning. Use the actual registered identifiers in products and consumers; translating a package enum or a display label into a new feature name breaks that connection.

A sellable feature answers whether a customer is entitled to a capability. It does not turn on the runtime, assign an administrator role or establish a connection. Keep those decisions connected without treating them as one flag:

The standard settings destinations connect these layers. SSO uses CoreFeature.SINGLE_SIGN_ON and opens its configuration and connection resources. Provisioning uses DIRECTORY_PROVISIONING and opens its configuration and token resources. Audit streaming uses SECURITY_EVENT_EXPORT and opens its export configuration and failed deliveries. Each destination checks runtime availability and organization-management roles before presenting its entitlement-gated body.

See what a backend consumer actually requires

Selected engine example: the directory-management helper checks the exact organisation’s feature and then looks for an active (not revoked) provisioning token. These are the complete decision statements from scim-provisioning-gate.backend.utils.ts; function parameters and source comments are omitted:

const featureEnabled = await featureResolution.isFeatureEnabledAtScope(
  CoreFeature.DIRECTORY_PROVISIONING,
  ResourcePrimaryScope.ORGANIZATIONS,
  organizationId,
);
if (!featureEnabled) return false;

const activeToken = await systemAccessService.readAsSystem<{ _id: string }>(
  CoreResourceType.ORGANIZATION_SCIM_TOKENS,
  { organizationId, isActive: true },
  serviceOptions,
);
return activeToken != null;

Here organizationId is the already-established owner supplied by the calling engine workflow. readAsSystem is the engine helper’s trusted read, not an invitation to elevate a customer’s request. The result answers whether this organisation is actively directory-managed: an entitlement without an active token returns false. This management predicate deliberately does not check token expiry: an expired but unrevoked token still keeps the organisation classified as directory-managed. Token authentication and remote synchronization are separate checks; this result does not prove that the directory is reachable or that its next synchronization will succeed.

Different consumers have different contracts. Audit dispatch uses the selected organisation’s enabled SIEM configuration; it does not perform a fresh subscription lookup for every event. Do not infer an instantaneous delivery change from a plan change or from a settings tab disappearing. Follow the integration’s actual configuration and cache lifecycle.

Granting is not configuring

SSO needs a valid connection and provider configuration. Directory provisioning needs its enabled runtime and scoped provisioning credentials. Outgoing security-event delivery needs a destination. These are operational prerequisites even when the product includes the entitlement.

DIRECTORY_PROVISIONING, SINGLE_SIGN_ON and SECURITY_EVENT_EXPORT are independent definitions. Do not infer dependencies from a marketing bundle or from neighbouring settings tabs. M2M_WEBHOOK_DELIVERY also requires an exact-owner feature check because its definition has scopeBoundary: true.

Keep frontend discovery and backend decisions coherent

The standard settings destination makes an unavailable feature understandable; it is not a substitute for the backend integration’s own checks. Verify the service consumer, its required scope, and the configured provider when promising an enterprise control.

These feature names describe how an application packages capabilities for its customers. They do not define Wildo’s own open-core or commercial licensing boundary. That is a separate product decision, not something an enterprise label or a feature grant determines.

The settings hub selects an organisation; its registered resource operations keep that owner in the request path and execution context. The backend validates who may use those operations. Selecting a customer in the interface does not itself grant authority over that customer’s resources.

For SSO, configuration and connections are separate resources under the same owner. Domain verification establishes who controls the sign-in domain; connection settings describe how the identity provider participates. Neither should be copied into an application-wide credential merely because the application hosts both customers.

Exercise an organization-owned configuration operation

For example, the SSO domain-claim operation lets the organization’s administrator begin proving a domain it controls. The organization already has its seeded SSO configuration; claiming a domain does not require creating a second configuration row.

This request follows sso-domain-ownership.e2e.ts. Set BACKEND_URL, ORGANIZATION_ID and the organization’s administrator ACCESS_TOKEN; replace the illustrative domain with one the customer controls.

curl -X PUT \
  "$BACKEND_URL/organizations/$ORGANIZATION_ID/organization-sso-config/claim-domain" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"domain":"customer.example"}'

The claim response names the domain, reports pending and returns dnsName plus the one-time dnsRecordValue. Publish that exact value as a TXT record at the returned name. Do not invent the challenge value or assume that the domain’s presence in the stored list means it is verified.

After publishing the record, ask the same scoped operation family to verify it:

curl --fail-with-body -X PUT \
  "$BACKEND_URL/organizations/$ORGANIZATION_ID/organization-sso-config/verify-domain" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"domain":"customer.example"}'

Read the response’s status, not only the HTTP status code. A completed verification request can return HTTP 200 with failed; --fail-with-body cannot detect that business result. The backend checks DNS and rechecks competing ownership at verification time, before granting routing authority. A claim alone does not authorize sign-on routing.

This illustrates the ownership contract: a public, named operation changes the selected organization’s configuration and returns the next action its administrator needs. Provider connection details and SSO enforcement remain separate settings; the general configuration update is an internal operation, not a public catch-all HTTP endpoint.

Configure the correct integration owner

Enable the relevant feature and configure the provider through its declared resource. A page appearing in settings is a consumer of that configuration, not proof that a provider is already connected or operating.

Preserve the distinction between personal and organization connections

A person’s connected account and an organization-owned credential represent different authority. Use the appropriate resource and runtime context rather than copying credential material into generic application settings.

This capability describes the integrations with organization-owned configuration. It does not imply that every external provider supports every ownership mode. See the individual sign-on, provisioning and machine-access guides for their setup and operation contracts.

Application example: charge for pages actually rendered. This complete illustrative product follows the engine’s METERED contract and the same per-unit monthly price structure as Wonder Todos’ API-call product. The key and price below are example product choices, not an existing application offer:

import {
  ProductType, ResourcePrimaryScope, UsageAggregationType,
  type ProductDefinition,
} from '@wildo-ai/saas-models';
import { PricingModel, BillingInterval } from '@wildo-ai/external-connectors-models';
import { AvailableCurrency } from '@wildo-ai/zod-decorators';

export const renderedPagesProduct: ProductDefinition = {
  key: 'rendered_pages',
  type: ProductType.METERED,
  targetScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  prices: [{
    model: PricingModel.PER_UNIT,
    unitPrice: { amount: 1n, decimals: 2, currency: AvailableCurrency.USD },
    interval: BillingInterval.MONTH,
    intervalCount: 1,
    usageAggregation: UsageAggregationType.SUM,
    isDefault: true,
  }],
};

Add this product to the catalogue contributed by the owning shared module’s productDefinitions. Here 1n with two decimals means USD 0.01 per page. Billing/provider setup and catalogue synchronization must make the metered product available, and the organization must have an active or trialling subscription containing it. The product key is also the meter-event name used when reporting usage.

Connect the operation’s completed result

This complete illustrative operation entry belongs under the report resource’s registered custom render operation. The application still supplies its renderer implementation; the example defines its usage contract and response shape:

import { z } from 'zod';
import {
  CORE_ORG_ROLES, CoreResourceOperation,
  ResourceOperationRiskLevel, ResourceOperationVariantType,
  type OperationConfig_ForKey,
} from '@wildo-ai/saas-models';

export const renderReportOperation: OperationConfig_ForKey<string> = {
  variants: [{
    variantType: ResourceOperationVariantType.API_CALL,
    isDefault: true,
    resourceOperationLike: CoreResourceOperation.UPDATE,
    riskLevel: ResourceOperationRiskLevel.MEDIUM,
    roles: [CORE_ORG_ROLES.ORG_MEMBER],
    requestDto: z.object({}),
    customResponseDto: z.object({ pageCount: z.number().int().nonnegative() }),
  }],
  recordsUsage: {
    productKey: 'rendered_pages',
    quantityFromResultField: 'pageCount',
  },
};

The custom implementation returns the number it actually produced:

{ "pageCount": 3 }

After successful work, the shared operation hook reads recordsUsage from the resolved operation. In an eligible organization context, this result records three units for rendered_pages, initially pending provider reporting. Reading the number from the result avoids treating the requested page count as work completed.

recordsUsage sits beside variants; it is not an input field sent by the browser. Its quantity source can instead be a fixed quantity (default one). Choose either a fixed quantity or quantityFromResultField, not both. A nested result uses a dot path such as render.pageCount.

Complete the billing chain

The scope needs a billing account and an active or trialling subscription containing that metered product. The application also needs billing/provider registration and the configured flush job. A price on a metered product alone creates no usage.

Fixed quantities describe units per successful operation. Result-derived quantities must resolve to finite non-negative numbers; zero writes nothing. An invalid result path or absent eligible subscription records nothing and logs why. The hook runs asynchronously after the operation, so its failure does not turn committed work into a request failure.

Distinguish recorded, reported and charged

The flush drains pending rows in pages, groups quantities according to the product policy and uses a stable event identifier for retries. A temporarily missing provider customer mapping remains retryable. Reconciliation reports quantities, not merely row counts, so an operator can see what remains pending or could never be billed.

Provider reporting is not the same as an invoice being paid. The usage dashboard’s summary read is also not the complete settlement report. Monitor failed recording and pending flush quantities as part of operating usage-based pricing.

A CREDIT_PACK product needs purchaseConfig.creditPoolKey and its creditsPerUnit; the product type alone is insufficient. Register the product and complete checkout through the verified provider event path. The creditPools.enabled configuration flag is a declared product setting, not the runtime switch that activates these operations.

This complete illustrative product sells a pack of 100 document credits. Its mapping is explicit; the similarly named Wonder Todos sample credit pack does not currently supply this purchase mapping:

import {
  ProductType, ResourcePrimaryScope, type ProductDefinition,
} from '@wildo-ai/saas-models';
import { PricingModel } from '@wildo-ai/external-connectors-models';
import { AvailableCurrency } from '@wildo-ai/zod-decorators';

export const documentCreditPack: ProductDefinition = {
  key: 'document-credit-pack',
  type: ProductType.CREDIT_PACK,
  targetScopes: [ResourcePrimaryScope.ORGANIZATIONS],
  purchaseConfig: {
    creditPoolKey: 'documents',
    creditsPerUnit: 100,
    maxQuantityPerPurchase: 10,
  },
  prices: [{
    model: PricingModel.FLAT,
    unitPrice: { amount: 2500n, decimals: 2, currency: AvailableCurrency.USD },
    intervalCount: 1,
    isDefault: true,
  }],
};

Register it in the shared module’s product catalogue and complete the configured checkout path. In this example, quantity two costs two packs and maps to 200 credits in the account’s documents pool. The verified payment-event handler applies the top-up; the checkout-return page does not award credits.

The settlement handler reads that mapping and computes the top-up:

// Read product to check if it's a CREDIT_PACK
const products = await this.servicesRegistry.list<Product>(
  CoreResourceType.PRODUCTS, execCtx, { key: productKey },
) as Product[];
const product = products.length > 0 ? products[0] : null;

if (product?.type === ProductType.CREDIT_PACK && product.purchaseConfig?.creditPoolKey) {
  const credits = (product.purchaseConfig.creditsPerUnit ?? 1) * quantity;
  const poolKey = product.purchaseConfig.creditPoolKey;

  // Find the credit pool, auto-create if first purchase
  let pools = await this.servicesRegistry.list<CreditPool>(
    variants.creditPool, execCtx,
    { [variants.billingAccountFkField]: billingAccountId, poolKey },
  ) as CreditPool[];

This selected engine fragment precedes pool creation if needed and the internal TOP_UP call. The surrounding handler uses a durable settlement claim before effects; it does not grant credits from the browser’s checkout-return URL. Claim acquisition, credit top-up and the applied marker are separate writes: the guarded debit protects the balance, but this example does not establish crash-atomic payment settlement.

Consume credits from trusted service code

CreditPool_Operations.CONSUME and TOP_UP are INTERNAL_CALL operations. Resolve the pool for the correct organisation/user billing account and invoke consumption from the backend workflow that owns the paid action. The browser cannot award itself a balance.

This complete illustrative backend helper uses the public service registry. Its caller must first authorize the paid action, resolve its organization billing account server-side, and supply an execution context appropriate for these internal billing operations. The account identifier and credit price are trusted inputs from that workflow, not values copied from a browser request:

import {
  CoreResourceType, CreditPool_Operations, type CreditPool,
} from '@wildo-ai/saas-models';
import type {
  ExecutionContext, ServicesRegistryHandlerBackendService,
} from '@wildo-ai/saas-backend-lib';

export async function consumeDocumentCredits(
  services: ServicesRegistryHandlerBackendService,
  context: ExecutionContext<any>,
  organizationBillingAccountId: string,
  credits: number,
): Promise<CreditPool | null> {
  const pools = await services.list<CreditPool>(
    CoreResourceType.ORGANIZATION_CREDIT_POOLS,
    context,
    { organizationBillingAccountId, poolKey: 'documents' },
  );
  const pool = pools[0];
  if (!pool) return null;

  return services.executeCustomOperation<CreditPool>(
    CoreResourceType.ORGANIZATION_CREDIT_POOLS,
    CreditPool_Operations.CONSUME,
    context,
    pool._id,
    { credits },
  );
}

The helper selects by billing account and pool key before using the resulting ID. A user-owned purchase uses the separate user credit-pool resource and userBillingAccountId; substituting only the ID would not establish that ownership.

Await consumption before starting the paid work. null means no matching pool exists; the caller can offer purchase and must not proceed. An insufficient balance rejects with BILLING_INSUFFICIENT_CREDITS; let the application’s normal error handling explain that refusal. Other storage or execution failures also stop this helper from returning a successful spend. The declared DTO requires at least one credit.

For a pool with ten available credits, consuming three returns seven available and raises totalConsumed by three. Attempting to consume eight next is refused and does not debit the seven. This illustrates the balance contract, not a new executed payment journey.

The consume implementation performs this guarded change:

const { credits } = input;

const result = await utils.repositoriesRegistry.atomicGuardedMutation(
  variantResourceType,
  { _id, available: { $gte: credits } },
  { increment: { available: -credits, totalConsumed: credits } },
  executionContext,
);

The adapter-neutral mutation requires available >= credits, decrements availability and increments consumption together. Insufficient balance returns a business-rule refusal. Addition increments both availability and purchased totals, preserving concurrent top-ups.

Decide what happens around the paid work

Balance safety does not decide your business workflow. Specify when to consume, how to handle work that fails after consumption and which operation can compensate it. A metered-usage declaration does not automatically consume prepaid credits: metering records a quantity for later billing; a credit pool spends existing capacity.

For verification, test a paid settlement, a repeated delivery and competing spends near zero. Keep checkout activation and product mapping in the setup: the sample catalogue’s credit-pack name alone does not prove those prerequisites are authored.

Create the promotion through its trusted internal operation with a configured billing provider. The promotions.enabled flag records a product setting; the current runtime does not use it to switch promotion operations on or off. Choose a compatible discount type and amount. The creation hook syncs a coupon before saving provider identifiers; a failed provider sync does not leave a usable local-only offer.

The actual coupon request is:

const provider = getBillingProvider();
const couponResult = await provider.createCoupon({
  ...(input.discountType === DiscountType.PERCENTAGE && { percentOff: input.discountPercentage }),
  ...(input.discountType === DiscountType.FIXED_AMOUNT && input.discountFixedAmount && {
    amountOff: toCurrencyMinorUnitAmountOrThrow(input.discountFixedAmount, 'promotion fixed discount'),
    currency: input.discountFixedAmount.currency,
  }),
  duration: durationMap[input.duration] ?? 'once',
  ...(input.durationInMonths && { durationInMonths: input.durationInMonths }),
  ...(input.maxRedemptions && { maxRedemptions: input.maxRedemptions }),
  ...(input.metadata && { metadata: input.metadata }),
});
const providerCouponId = couponResult.providerCouponId;

let providerPromotionId: string | undefined;
if (input.type === PromotionType.PROMOTION_CODE && input.code && providerCouponId) {
  const promoResult = await provider.createPromotionCode(providerCouponId, input.code);
  providerPromotionId = promoResult.providerPromotionId;
}

This selected engine fragment follows input validation. Percentage offers need discountPercentage; fixed offers need discountFixedAmount. A PROMOTION_CODE also creates a provider promotion code. Persisted provider IDs are required by checkout.

Fixed discounts use the shared money contract: amount together with decimals describes the value. Wildo converts it to the provider currency’s minor units before creating the coupon. For example, USD amount: 5n, decimals: 0 and amount: 500n, decimals: 2 both send 500 cents. Values that would lose currency precision or exceed a safe provider number are refused before submission.

Preview, then revalidate at checkout

The client-facing APPLY operation validates the record and returns discount information; it records no redemption. OPEN_CHECKOUT separately revalidates the supplied code and passes the provider-backed discount into checkout. Do not treat a successful preview as a reservation or proof that a later purchase must remain eligible.

A guarded increment prevents the local counter from exceeding its configured cap under competing settlements. That cannot undo a provider discount already paid for; the handler logs that condition and still grants the purchased item. Keep provider restrictions consistent with the offer rather than treating the local count as an atomic reservation across external checkout sessions.

Deactivation prevents new eligible use; it is not a refund of earlier purchases. A referral-programme promotion type also does not implement referral conversion or reward delivery by itself.

ReferralSchema carries the referrer account, the referred account, a globally unique code, status, dates and two reward-applied flags. Each account reference has its own scope discriminator, so one relationship cannot assume the other account is also organisation-scoped.

The referrer reward contract is:

export const ReferrerRewardSchema = z.object({
  type: z.enum(ReferrerRewardType),
  /** Credit amount (for CREDIT type), discount percentage (for DISCOUNT), etc. */
  value: z.number().min(0),
  /** Credit pool key (for CREDIT type) */
  creditPoolKey: z.string().optional(),
  /** Feature key (for FEATURE type) */
  featureKey: z.string().optional(),
  /** Duration in days (for temporary rewards) */
  durationDays: z.number().min(1).optional(),
  /** Commission percentage (for COMMISSION type) */
  commissionPercentage: z.number().min(0).max(100).optional(),
});
export type ReferrerReward = z.infer<typeof ReferrerRewardSchema>;

This is the actual model declaration. It can represent credit, feature, discount or commission details according to the reward kind; the referred reward additionally supports trial extension. A declared durationDays is stored policy, not an automatic scheduler.

Supply the application-owned steps

The engine’s referral resource exposes internal operations. There is no standard customer share-code route or automatic subscription-to-referral conversion service. Invoke the registered resource through trusted backend code; author a public flow only with its own access and input rules.

Keep reward state honest

The applied booleans are bookkeeping fields, not a transaction or deduplication mechanism by themselves. The application must arrange the claim and reward effect so repeated events cannot pay twice, and failed effects remain distinguishable from completed ones. Credit-pool balance operations can supply the credit mutation, but the referral still owns when and why it happens.

Treat the schema’s lifecycle commentary as the intended shape, not proof of a running reward engine. A promotion typed as a referral programme can describe the offer without executing this workflow. The referral code’s usage-data classification also matters when designing retention and subject-data handling.

Author a definition, then register it

A template directory contains template.tsx and locale label modules such as labels.en.ts. The template default-exports EmailTemplateDefinition<Labels>, with a subject function and a body function. Wonder Todos’ password-reset template starts with:

Selected from template.tsx; surrounding module configuration is omitted.

import * as React from 'react';
import type { EmailTemplateDefinition } from '@wildo-ai/saas-backend-lib';
import { EmailLayout, HeadingText, BodyText, PrimaryButton, AlertBox, Divider } from '~backend-api/engine/email/components'
import type { PasswordResetLabels } from './labels.en';

const template: EmailTemplateDefinition<PasswordResetLabels> = {
  subject: ({ context, labels }) =>
    `${labels.subject} — ${context.objectContext.primaryScopeContext.appName}`,

  body: ({ context, brand, labels }) => {
    const appName = context.objectContext.primaryScopeContext.appName;
    const { resetUrl, expiresInMinutes } = context.additionalContext as {
      resetUrl: string;
      expiresInMinutes: number;
    };

    return (
      <EmailLayout brand={brand} appName={appName} logoUrl={context.objectContext?.primaryScopeContext?.logoUrl} previewText={labels.subject}>
        <HeadingText brand={brand}>{labels.heading}</HeadingText>
        <BodyText brand={brand}>
          {labels.body.replace('{appName}', appName)}
        </BodyText>
        <PrimaryButton href={resetUrl} brand={brand}>
          {labels.button}
        </PrimaryButton>
        <BodyText brand={brand} muted style={{ marginTop: '24px' }}>
          {labels.expiry.replace('{expiresInMinutes}', String(expiresInMinutes))}
        </BodyText>
        <Divider brand={brand} />
        <AlertBox variant="info" brand={brand}>
          <BodyText brand={brand} muted style={{ margin: 0, fontSize: '14px' }}>
            {labels.safetyTitle}
          </BodyText>
        </AlertBox>
      </EmailLayout>
    );
  },

  description: 'Password reset email with secure reset link, expiry notice, and safety disclaimer.',
};

export default template;

The application scanner loads compiled template modules and produces emailTemplateDefinitions; its owning backend module contributes that map to the initialization registry at startup. System directories become system.<name> references; resource directories become email.<resource>.<operation>.<target> references. Match the exact runtime reference, including a variant or custom notification suffix when used.

Keep rendering independent from the browser

Use email-safe React components and the supplied context. Do not import SPA state, hooks or application screens. Keep visible wording in label modules; the same layout then renders with the selected locale. Shared header and footer components are ordinary template imports, not database-managed templates.

The scanner reads compiled output. After authoring, use the normal application development pipeline and verify the resolved template in the companion. A source file that has not reached the scanned output is not yet available to the running sender.

Compose the layout inside each template

The application owns its email components. Wonder Todos’ EmailLayout passes brand values and the resolved logo to a header, wraps message-specific children and renders a shared footer:

Selected from EmailLayout.tsx; surrounding module configuration is omitted.

          <EmailHeader brand={brand} appName={appName} logoUrl={logoUrl} />
          <Section style={{ padding: '32px' }}>
            {children}
          </Section>
          <Section style={{ padding: '0 32px 32px 32px' }}>
            <EmailFooter brand={brand} appName={appName} supportEmail={supportEmail} />
          </Section>

A template imports this layout and supplies brand, appName, logoUrl and its child content. Password reset, verification and business notifications can then share spacing and styling without sharing the same words.

Keep the shared boundary useful

Put recurring presentation in components; keep the action URL, expiry and scenario-specific safety text in the template. The logo comes from context.objectContext.primaryScopeContext.logoUrl, not from an invented brand-token property. Email-safe HTML and inline styles are used because rendering happens outside the application’s browser interface.

Inspect several representative templates after changing shared components. A working reset email alone does not prove that a longer translated invoice or invitation still fits its layout.

Author the values in backend configuration

Application example for the email section of backend-api/src/saas-config.backend.ts, using the fields accepted by EmailBrandTokens_ConfigSchema. Keep the other backend settings; replace the illustrative sender with your configured sending identity.

email: {
  from: 'noreply@example.com',
  brandTokens: {
    primaryColor: '#245b8a',
    secondaryColor: '#60758a',
    fontFamily: 'Arial, Helvetica, sans-serif',
  },
},

These inputs override the corresponding email defaults. fontFamily also supplies headingFontFamily; other palette values retain their defaults. The token builder converts supported color inputs to email-style values. It does not derive an entire theme from the primary color or load the application’s web CSS.

Read the email brand object in components

EmailBackendService builds EmailBrandTokens from the backend email configuration and passes them to the subject/body render functions. The layout consumes these values explicitly:

Selected from EmailLayout.tsx; surrounding module configuration is omitted.

      <Body style={{
        backgroundColor: brand.mutedColor,
        fontFamily: brand.fontFamily,
        margin: 0,
        padding: '40px 0',
      }}>
        <Container style={{
          maxWidth: '600px',
          margin: '0 auto',
          backgroundColor: brand.backgroundColor,
          border: `1px solid ${brand.borderColor}`,
          borderRadius: brand.borderRadius,
        }}>
          <EmailHeader brand={brand} appName={appName} logoUrl={logoUrl} />
          <Section style={{ padding: '32px' }}>
            {children}
          </Section>
          <Section style={{ padding: '0 32px 32px 32px' }}>
            <EmailFooter brand={brand} appName={appName} supportEmail={supportEmail} />
          </Section>
        </Container>
      </Body>

The layout above uses the shared font and neutral palette. Components such as PrimaryButton use brand.primaryColor for the action. Preview both together after changing the configuration: only components that read a changed token should change.

Supply the logo through context

Pass the resolved primaryScopeContext.logoUrl to the shared header. It is an absolute email-appropriate asset URL resolved for the send context. Colors and fonts belong to brand; logo identity belongs to context. Keeping these separate lets the sender provide the appropriate asset without hard-coding it into every template.

Companion preview and test-send share the configured absolute logo resolution and support the same context overrides. Use an explicit context override to inspect another identity; choosing a recipient does not load that recipient’s organization.

Preview the generated HTML, including long translations and missing optional logos. A component that never reads a token will not change merely because that token was configured.

Pair the layout with locale labels

Author labels.<locale>.ts beside template.tsx and export the typed labels. Register the compiled template and labels through emailTemplateDefinitions. Keep the subject, button and body wording in labels so they follow the same locale decision.

The current registry builds this fallback order:

Selected from email-template-registry.backend.service.ts; surrounding module configuration is omitted.

    const candidates = [locale];
    const baseLanguage = locale.includes('-') ? locale.split('-')[0] : null;
    if (baseLanguage && baseLanguage !== locale) {
      candidates.push(baseLanguage);
    }
    if (fallbackLocale && !candidates.includes(fallbackLocale)) {
      candidates.push(fallbackLocale);
    }
    if (!candidates.includes(primaryLocale)) {
      candidates.push(primaryLocale);
    }

It tries the requested locale, its base language, the configured fallback locale and finally the primary locale, without duplicates. If no entry resolves, it reports the missing template rather than silently loading a database copy.

Resolve the recipient, not the person causing the event

The operation dispatcher reads each recipient’s language preferences and passes the selected locale to the sender. A customer receiving a notification should not inherit an administrator’s interface language. Direct email-by-address notifications have no user preference record and use application defaults.

The companion translation workflow writes additional label files. Review meaning and placeholders after translation, then preview the actual template in the target locale. Translation does not create the business trigger or change the message’s recipient policy.

Use registration diagnostics before a fallback hides a gap

When the template registry initializes, it checks required system references in the configured primary language. For enabled secondary languages, it checks every registered reference, including resource-operation templates. A base-language file counts: labels.fr.ts covers a request for fr-CA. Falling all the way back to the primary language does not count as translated coverage.

For the French-Canadian example, author labels.fr.ts beside the existing template with the same exported label keys. Regenerate/compile the application’s email files through its normal development workflow, inspect the next registry-initialization diagnostics, then preview that template with fr-CA. Confirm the subject, button and body use French and that placeholders still interpolate correctly.

These diagnostics report missing coverage; they do not block every send or create translations. A working primary-language fallback can keep delivery possible while still leaving the recipient with the wrong language.

Use user context instead of the initiating actor

Resource-operation notifications fetch the recipient’s user identity, profile and preferences. Name fields belong to the profile, while the user row supplies the email anchor. The dispatcher combines them as follows:

Selected from notifications-dispatcher.backend.service.ts; surrounding module configuration is omitted.

      const fullName = [profile?.firstName, profile?.lastName].filter(Boolean).join(' ') || undefined;
      const displayName = profile?.displayName ?? fullName ?? email;
      const firstName = profile?.firstName ?? email;

      const preferredLanguage = this.normalizeAvailableLanguage(preferences?.languagePreferences?.primaryLanguage)
        ?? this.normalizeAvailableLanguage(preferences?.regional?.locale);

Templates can read context.userContext.name or firstName; the selected recipient language is used when resolving labels. The operation’s author and its notification recipient may be different people, so do not substitute the initiator’s name.

Preserve a meaningful fallback

A newly provisioned or invited account may not have a profile. The dispatcher falls back from display name to full name to email; first name likewise falls back to email. Templates should not invent a name or leave an unresolved interpolation token.

For direct-by-address email, provide only the context that actually exists. That path has no member profile to consult. Keep the generic greeting suitable for a person who has not registered yet.

Start with the stable contract

SystemEmailTemplateRegistry identifies the message, routing classification and expected event data. This complete password-reset entry is selected from the shared registry; imports and neighboring entries are omitted:

[SystemEmailTemplateRef.PASSWORD_RESET]: {
    templateRef: SystemEmailTemplateRef.PASSWORD_RESET,
    type: EmailTemplateType.TRANSACTIONAL,
    frequency: EmailTemplateFrequency.RECURRENT,
    scope: EmailTemplateScope.APPLICATION,
    eventDataSchema: z.object({
      resetUrl: z.url(),
      expiresInMinutes: z.number().int().positive(),
    }),
  },

The application supplies backend-api/src/engine/email/system/password-reset/template.tsx and its labels.<locale>.ts files. The scanner turns password-reset into system.password_reset; the backend module contributes the resulting emailTemplateDefinitions to initialization. The shared registry describes the expected payload; the send path does not automatically parse additionalContext against eventDataSchema, so caller and template must agree.

See where sending begins

The existing password-reset service creates the token and URL, resolves the recipient’s language, then calls EmailBackendService.send with SystemEmailTemplateRef.PASSWORD_RESET. Its supplied additionalContext contains resetUrl and expiresInMinutes. The complete sending example shows that call and its outcome handling.

The application template turns those values into an action. Selected from Wonder Todos’ password-reset body; the surrounding EmailLayout and other text are omitted:

<HeadingText brand={brand}>{labels.heading}</HeadingText>
<BodyText brand={brand}>{labels.body.replace('{appName}', appName)}</BodyText>
<PrimaryButton href={resetUrl} brand={brand}>
  {labels.button}
</PrimaryButton>
<BodyText brand={brand} muted style={{ marginTop: '24px' }}>
  {labels.expiry.replace('{expiresInMinutes}', String(expiresInMinutes))}
</BodyText>

Customize labels and shared presentation while preserving the context and reference. Trigger the local password-reset flow to inspect the generated message and link; a template preview alone only verifies rendering.

Keep contracts and active flows distinct

A catalogue entry does not create a trigger. Organization invitations, for example, use a resource-operation email reference. When adding a flow, name its producer and supplied context rather than assuming that registering a template schedules or sends it.

Read the message contract before editing its words

System-email specifications are built from the corresponding registry entry, then add purpose, tone, usage guidance and text-slot meanings. The password-reset specification begins:

Selected from authentication.system-emails.specification.ts; surrounding module configuration is omitted.

export const passwordResetSystemTemplateSpecification = systemEmailTemplateSpecificationFromRegistryEntry(
  SystemEmailTemplateRegistry[SystemEmailTemplateRef.PASSWORD_RESET],
  () => ({
    purpose: 'Allow an account owner to re-establish control over their credentials through a secure, time-bound link.',
    tone: 'Clear, security-aware, and low-drama — the user asked for this or might not have, so the copy must help both cases without alarming either.',
    useWhen: 'Use only in response to an explicit password-reset request initiated by the account or by an administrator.',
    avoidWhen: 'Do not use for proactive password hygiene nudges; those belong to security-alert or security-digest surfaces.',
    textSlots: {
      subject: {
        purpose: 'Signal that this is a password-reset email and convey that action is required within a limited window.',
      },
      previewText: {
        purpose: 'Restate the secure-reset intent with the expiration timeframe so recipients can triage in their inbox.',
      },
      body: {
        purpose: 'Short paragraph explaining who requested the reset (or inviting the recipient to ignore the email if not them) and how the link works.',
      },
      ctaLabel: {
        purpose: 'Primary action label that sends the user to `eventData.resetUrl`.',
      },
      expirationNotice: {
        purpose: 'Inline reminder about `eventData.expiresInMinutes` — makes the time-bound nature of the link visible near the CTA.',
        notes: ['Surface the minute count as numeric text; downstream locales must format it naturally (for example "30 minutes").'],
      },
      securityFootnote: {
        purpose: 'Closing guidance for recipients who did not request this reset, asking them to ignore or contact support.',
      },
    },
    eventData: {
      purpose: 'Payload carrying the secure reset URL and expiration window used throughout the body.',
    },
    businessConstraints: [
      'Never leak user identifiers, IP addresses, or authentication method details in this email — those belong to security alerts.',
      'Never reuse this template for email verification or magic-link flows; each has its own trust profile.',
    ],
    codeHandling: {
      definitionOwner: ENGINE_OWNER_REF,
      templateRefDeclaration: TEMPLATE_REF_DECLARATION,
      eventDataSchemaSymbol: EVENT_DATA_SCHEMA_SYMBOL,
    },
  }),
);

The application exports systemEmailTemplateSpecifications from its specification package. The companion’s email specification loader renders the applicable concern into generation or translation context. This supplies intent to the authoring tool; it does not replace the runtime template or send the message.

Review meaning as well as shape

A valid TSX result can still be poor product communication. Check that the action, expiry and safety advice remain clear and that the translation preserves their meaning. Keep context fields aligned with the actual sender: the template consumes its concrete runtime context, not a promise inferred solely from the specification.

Use specification changes when the purpose changes; use label changes when only wording changes. That separation keeps a stylistic rewrite from quietly changing the account-recovery contract.

Work through the application’s companion

The Wildo CLI email commands reach the running development companion in application scope. The generation command can target template references, generation starts with the primary locale, and translation produces the other locale labels. Preview renders the chosen reference and locale; test-send additionally requires a recipient and uses the configured email path. Both use the configured email logo and support the same context overrides; the recipient address does not supply a real user or organization context.

From the application root with its companion running, preview an existing password-reset template:

wildo generate email preview \
  --template system.password_reset \
  --locale en \
  --out /tmp/password-reset-preview.html

The template reference and locale are required by email-preview.command.ts; --out selects the rendered HTML file. Open that file to review the message. Use a locale actually registered by the application. This example invokes preview only; test-send is a separate command that additionally requires --to and runs the configured sending path. With the local preview provider, it renders and logs without a network submission.

Inspect the artifact you will ship

The companion writes TSX and label files, validates their consistency and refreshes its template registry. Preview can produce an HTML file, which lets you inspect actual layout rather than only a subject line in the terminal. Generation can use the system email’s specification context, but the author still reviews the output.

Check placeholders, links, brand assets and target-language layout. A preview with synthetic context does not establish that a real operation supplies the same data. Finish by exercising the message’s producer with the local preview provider, then use a real provider test when validating deployment delivery.

Declare the providers on the process that sends

Application configuration has two jobs: enable EMAIL_TRANSACTIONAL in engineCapabilities, then make its providers available in the backend scope. Selection chooses among that declared set; it cannot install an undeclared provider.

Application example, reduced from Wonder CRM’s wildo.saas.config.ts to the complete email-provider section. Assign emailProviders to the existing configuration’s providers property, merging the other provider scopes your application uses.

import { EngineCapability } from '@wildo-ai/saas-models';
import { defineSaaSProviders } from '@wildo-ai/platform-config-lib';

const emailProviders = defineSaaSProviders({
  scopes: {
    backend: {
      providers: {
        resend: {
          engineCapabilities: [EngineCapability.EMAIL_TRANSACTIONAL],
          providerCapabilities: ['EMAIL_TRANSACTIONAL'],
          protocols: ['EMAIL_PROVIDER'],
        },
        'email-preview': {
          engineCapabilities: [EngineCapability.EMAIL_TRANSACTIONAL],
          providerCapabilities: ['EMAIL_TRANSACTIONAL'],
          protocols: ['EMAIL_PROVIDER'],
        },
      },
      selection: {
        [EngineCapability.EMAIL_TRANSACTIONAL]: { primary: 'resend' },
      },
    },
  },
});

Keep [EngineCapability.EMAIL_TRANSACTIONAL]: { enabled: true } in the application’s engineCapabilities. The declaration makes both providers reachable; the selection makes Resend the default. Backend saas-config.backend.ts supplies email.from, and the existing backend module supplies emailTemplateDefinitions.

Change only the local selection

Wonder CRM’s infrastructure/local/wildo.infra.local.config.ts contains this property inside its infrastructure configuration:

providerSelection: {
  [EngineCapability.EMAIL_TRANSACTIONAL]: {
    primary: 'email-preview',
  },
},

Local messages now render into logs; environments without that override retain Resend. Supply RESEND_API_KEY through the sending environment’s secret configuration and use a sender accepted by that provider. Keep credentials out of templates and tracked configuration.

From the application root, wildo config sync --env local regenerates the local configuration and environment artifacts. Inspect the generated backend provider runtime for both declared references and check the effective local selection. A send through the local flow should return LOCAL_PREVIEW; a network provider reports its own classified submission result.

Selection is not retry failover

Email resolves one provider for a send. Availability selection and an environment override do not mean a failed network submission is automatically retried with another vendor. Interpret the sender’s outcome and retryability: an uncertain response may already represent an accepted message.

Register before selecting

An environment override only selects an available provider. In wildo.saas.config.ts, add the following entry to providers.scopes.backend.providers, alongside the production provider. This is the complete entry used by Wonder CRM:

'email-preview': {
  engineCapabilities: [EngineCapability.EMAIL_TRANSACTIONAL],
  providerCapabilities: ['EMAIL_TRANSACTIONAL'],
  protocols: ['EMAIL_PROVIDER'],
},

Keep EMAIL_TRANSACTIONAL enabled, the template-bearing backend module registered and email.from configured. EngineCapability is imported from @wildo-ai/saas-models. The preview provider needs no API credential.

Inside infrastructure/local/wildo.infra.local.config.ts, select it for the local environment:

providerSelection: {
  [EngineCapability.EMAIL_TRANSACTIONAL]: {
    primary: 'email-preview',
  },
},

Run wildo config sync --env local from the application root to refresh the generated provider and environment configuration. Keep the ordinary application selection on the deployment provider; a local override need not change staging or production.

Trigger a message and inspect the result

For the invitation example, perform the application’s invitation operation and inspect the backend email-preview log. Check the recipient, subject and acceptance URL produced by that operation. This exercises recipient resolution, locale, context and rendering before the preview provider logs the content.

The returned outcome is EmailSubmissionOutcome.LOCAL_PREVIEW, with success: true, retryable: false and no provider receipts. Companion test-send and CLI output preserve that outcome; it does not describe provider acceptance or inbox delivery.

Choose the inspection surface for the question

Local logs may contain usable invitation or recovery links. Keep them within the development environment. For the full availability/default/local-override arrangement, follow provider selection.

Make Brevo available and select it

Application example adapted from the existing backend-scope pattern and Brevo’s module contract. Merge this email section into wildo.saas.config.ts; keep the application’s other capabilities and providers.

import { EngineCapability } from '@wildo-ai/saas-models';
import { defineSaaSProviders } from '@wildo-ai/platform-config-lib';

const emailProviders = defineSaaSProviders({
  scopes: {
    backend: {
      providers: {
        brevo: {
          engineCapabilities: [EngineCapability.EMAIL_TRANSACTIONAL],
          providerCapabilities: ['EMAIL_TRANSACTIONAL'],
          protocols: ['EMAIL_PROVIDER'],
        },
      },
      selection: {
        [EngineCapability.EMAIL_TRANSACTIONAL]: { primary: 'brevo' },
      },
    },
  },
});

Assign emailProviders to the existing config’s providers property and enable EMAIL_TRANSACTIONAL in its engineCapabilities. In backend configuration, set email.from. Put BREVO_API_KEY in the target environment’s secret providerEnv, not in this provider declaration. Regenerate with wildo config sync --env <environment> from the app root, then inspect the backend provider runtime and emitted environment.

Supply the inputs the adapter actually reads

These are the engine adapters’ current configuration contracts, not a comparison of vendor plans.

For Mailgun, the email resolver reads the selected provider configuration’s domain, or MAILGUN_DOMAIN from its environment. This must be the sending domain, not merely the application’s website host. It refuses to send when the required endpoint domain is absent.

Verify the handoff, not just the configuration

Use a registered template and inspect EmailSendResult: outcome, submission identity and provider receipts. The normal sender uses the same template/context API across adapters, while each adapter supplies encoding, authentication and result classification. Attachment ceilings and idempotency support can differ; changing a provider does not erase those differences.

An accepted submission confirms the provider handoff. It does not establish inbox placement. Marketing capability support is a separate routing decision, not campaign orchestration.

Declare the classification on the template

Application example: a complete template.tsx for a promotional announcement, using the existing template interface. Its visible words come from the co-located labels file. Place it in the application’s resource-template tree under the reference your producer will request; register it through the same backend template map used by transactional messages.

import * as React from 'react';
import type { EmailTemplateDefinition } from '@wildo-ai/saas-backend-lib';
import { EmailTemplateType } from '@wildo-ai/saas-models';

type AnnouncementLabels = {
  subject: string;
  heading: string;
  body: string;
};
const template: EmailTemplateDefinition<AnnouncementLabels> = {
  type: EmailTemplateType.MARKETING,
  subject: ({ labels }) => labels.subject,
  body: ({ labels, brand }) => (
    <div style={{ fontFamily: brand.fontFamily, color: brand.foregroundColor }}>
      <h1>{labels.heading}</h1>
      <p>{labels.body}</p>
    </div>
  ),
};
export default template;

A matching labels.en.ts exports the words:

export const labels = {
  subject: 'Discover our new collection',
  heading: 'A new collection is here',
  body: 'Explore the latest additions in your account.',
};

The template’s declared type takes precedence over the caller’s requested type. It resolves EMAIL_MARKETING; the regular sender still submits an individual email request.

Make the marketing capability reachable

In wildo.saas.config.ts, enable [EngineCapability.EMAIL_MARKETING]: { enabled: true }. The following complete provider configuration section selects Brevo for marketing. Merge it with existing backend providers and keep transactional selection separate:

import { EngineCapability } from '@wildo-ai/saas-models';
import { defineSaaSProviders } from '@wildo-ai/platform-config-lib';

const marketingProviders = defineSaaSProviders({
  scopes: {
    backend: {
      providers: {
        brevo: {
          engineCapabilities: [EngineCapability.EMAIL_MARKETING],
          providerCapabilities: ['EMAIL_MARKETING'],
          protocols: ['EMAIL_PROVIDER'],
        },
      },
      selection: {
        [EngineCapability.EMAIL_MARKETING]: { primary: 'brevo' },
      },
    },
  },
});

Assign the merged configuration to providers, supply BREVO_API_KEY through the deployment secret configuration and configure email.from. Regenerate with wildo config sync --env <environment> from the application root.

Invoke the sender after the application’s audience decision

An explicit backend caller requests the registered reference through EmailBackendService.send, supplying the recipient, locale, context and type: EmailTemplateType.MARKETING. For example, the existing scanner maps resources/announcements/release to email.announcements.release; that is the reference a matching producer requests. Inspect the returned providerId and submission outcome to confirm the selected route.

Application caller example for that registered reference. The caller supplies a complete EmailSendRequest context and stable submission identity where retries are possible; this helper fixes the reference and classification without choosing an audience:

import type { EmailBackendService, EmailSendRequest } from '@wildo-ai/saas-backend-lib';
import { EmailTemplateType } from '@wildo-ai/saas-models';

export function sendAnnouncement(
  emailService: EmailBackendService,
  request: Omit<EmailSendRequest, 'templateRef' | 'type'>,
) {
  return emailService.send({
    ...request,
    templateRef: 'email.announcements.release',
    type: EmailTemplateType.MARKETING,
  });
}

Await the returned result and handle it using the submission outcome contract.

The application or an external tool owns consent, audience selection, unsubscribe handling and scheduling. This template and provider configuration do not create those workflows, nor do they turn an ordinary send into a campaign request. Keep recovery and security messages on their transactional route.

Prepare the application once

Enable EMAIL_TRANSACTIONAL, declare and select a backend EMAIL_PROVIDER, configure the sender and deployment credential, and register the file-based emailTemplateDefinitions through the backend module. Provider selection shows that complete configuration section.

A resource operation’s email declaration reaches the shared sender through the dispatcher. An explicit backend service can call EmailBackendService.send directly. In either case, the template reference must resolve in the runtime registry.

Follow a real caller

Selected, contiguous excerpt from auth-password-reset.backend.service.ts. The surrounding method has already created the reset token and URL, loaded the recipient’s preferences and resolved application identity. this.emailService is the injected EmailBackendService; token generation and service construction are omitted. This is the existing authentication producer, not a replacement password-reset implementation.

const emailResult = await this.emailService.send({
  submissionId: String(resetToken._id),
  templateRef: SystemEmailTemplateRef.PASSWORD_RESET,
  locale: userPreferences?.languagePreferences?.primaryLanguage
    ?? userPreferences?.regional?.locale
    ?? getConfiguredPrimaryLanguage(this.appConfigService.config),
  type: EmailTemplateType.TRANSACTIONAL,
  to: user.email,
  context: {
    currentObject: { email: user.email, userId: user._id },
    objectContext: {
      primaryScopeContext: {
        appName: appIdentity.appName,
        applicationId: this.appConfigService.applicationId,
        logoUrl: this.appConfigService.resolveBrandLogoAbsoluteUrl({
          composition: BrandAssetComposition.LOCKUP,
          purpose: BrandAssetPurpose.EMAIL,
        }) ?? undefined,
      },
    },
    userContext: { userId: user._id, email: user.email },
    additionalContext: {
      resetUrl,
      tokenValue: resetToken.token,
      expiresInMinutes: PASSWORD_RESET_TOKEN_TTL_HOURS * 60,
    },
  },
});
if (
  !emailResult.success
  || (emailResult.outcome !== EmailSubmissionOutcome.PROVIDER_ACCEPTED
    && emailResult.outcome !== EmailSubmissionOutcome.LOCAL_PREVIEW)
) {
  this.logger.error('Password reset email provider did not confirm acceptance', {
    userId: user._id,
    submissionId: emailResult.submissionId,
    outcome: emailResult.outcome,
    error: emailResult.error,
  });
} else {
  this.logDebug('Password reset email submission completed', {
    outcome: emailResult.outcome,
    userId: user._id,
    submissionId: emailResult.submissionId,
    providerMessageIds: emailResult.providerMessageIds,
  });
}

The token identity gives this logical submission a stable submissionId. The caller supplies recipient language, application/logo context and reset-specific values together, then handles both confirmed network acceptance and successful local preview. Other results enter its failure-reporting branch.

Give each outcome the right meaning

Use retryable and preserve the logical submission identity across a retry. A completed HTTP request is not the result contract, and provider acceptance is not inbox delivery. Attachments resolve through the file service and its access context before submission; missing or unauthorized content must not silently disappear.

Preserve the logical submission across attempts

For token-backed operation emails, the dispatcher derives an identity from the committed source, notification, template and recipient. The derivation does not place the raw recipient address in an idempotency header:

Selected from notifications-dispatcher.backend.service.ts; surrounding module configuration is omitted.

export function deriveEmailNotificationSubmissionId(
  sourceId: string,
  notificationIdentifier: string,
  templateRef: string,
  recipientIdentity: { email?: string; userId?: string },
): string {
  return createHash('sha256')
    .update(JSON.stringify({
      sourceId,
      notificationIdentifier,
      templateRef,
      recipientIdentity,
    }))
    .digest('hex');
}

The queued path persists a submissionId for each item. Providers that declare idempotency support receive the identity through their adapter-specific header or payload field. A custom sender must reuse an existing logical identity when retrying the same submission rather than minting a fresh one on each attempt.

Let the provider contract decide retry safety

The sender classifies confirmed acceptance, rejection and ambiguous transport outcomes. Batch retry uses the result’s retryable decision. A stable identity alone cannot guarantee duplicate prevention on a provider without the corresponding contract, nor guarantee inbox delivery.

RESEND deliberately mints a replacement token and represents a new logical message. Do not reuse the old submission identity for that new content. Token revocation and provider acceptance are separate: withdrawing a token cannot recall an email already accepted by the provider.

Declare the recipients normally

Use the same resource-operation email declaration for a small or large group. The dispatcher chooses the queue when its resolved user list exceeds EMAIL_BATCH_THRESHOLD; the current threshold is ten, an internal implementation choice rather than an application setting.

Selected from notifications-dispatcher.backend.service.ts; surrounding module configuration is omitted.

    const { templateRef, locale, baseContext } = await this.buildEmailNotificationContext(
      executionContext,
      functionParameters,
      notification,
    );

    if (userIds.length > EMAIL_BATCH_THRESHOLD) {
      await this.enqueueEmailBatch(
        templateRef,
        locale,
        userIds,
        baseContext,
        notification,
        emailSubmissionSourceId,
      );
      return [];
    }

Before enqueueing, it constructs per-recipient items with locale, context and stable submission identities. The registered email.batch-send custom batch executes through the application’s batch infrastructure and calls the same EmailBackendService.send pipeline as direct delivery. Keep the worker and queue infrastructure available in the deployment.

Follow individual outcomes

The batch result includes each recipient’s outcome, provider message IDs, retryability and attempt count. Retries preserve the stored submission identity and occur only when the result permits another attempt. Queueing is not proof that every provider accepted a message, and the operation’s immediate response does not contain the later batch results.

This fan-out handles operation emails. It does not add audience segmentation, scheduling or a marketing campaign lifecycle.

Put recipient intent on the operation

userNotifications belongs to the resource operation configuration. Targets can name the initiator, organization users or a selected user list. Wonder Todos’ change-status operation contains these two distinct custom email targets:

Selected from todos.resources-config.ts; surrounding module configuration is omitted.

        {
          target: CoreUserNotificationTarget.USERS_CUSTOM,
          channel: CoreUserNotificationChannel.EMAIL,
          customNotificationRef: 'notify-creator', // Required: distinguishes from 'notify-assignee'
          userIdsSelector: ({ currentObject, objectContext, initiatorIds }) => {
            return [ currentObject.createdByUserId ];
          }
        },
        {
          target: CoreUserNotificationTarget.USERS_CUSTOM,
          channel: CoreUserNotificationChannel.EMAIL,
          customNotificationRef: 'notify-assignee', // Required: distinguishes from 'notify-creator'
          userIdsSelector: ({ currentObject, objectContext, initiatorIds }) => {
            return currentObject.assignedToUserId ? [ currentObject.assignedToUserId ] : [];
          }
        }

The selector returns recipient user IDs from operation context. Distinct customNotificationRef values disambiguate repeated targets and their template references. Register templates matching those references; declaring an email target without its content is not a complete setup.

Give each declaration its registered content

The factory generates notification identities; the email resolver combines resource, operation, optional variant, target and custom reference. For the existing todos / change_status operation, these are the actual references:

The default creator template lives at backend-api/src/modules/tasks-manager/emails/resources/todos/change_status.users-custom_notify-creator/template.tsx, with its labels.en.ts alongside it. The other references have matching directories. Keep operation identifiers such as change_status intact; a URL spelling is not a template identity.

This is the complete existing scanner in emails/module-email-template-definitions.ts:

import {
  scanEmailTemplateDirectory,
  type EmailTemplateDefinition,
  type EmailTemplateDefinitionsMap,
} from '@wildo-ai/saas-backend-lib';

const moduleEmailTemplates = await scanEmailTemplateDirectory<EmailTemplateDefinition>({
  importMetaUrl: import.meta.url,
  subdir: 'resources',
  keyFromPath: (rel) => {
    const dotted = rel.replace(/\//g, '.');
    return `email.${dotted}`;
  },
});

export const moduleEmailTemplateDefinitions =
  moduleEmailTemplates satisfies EmailTemplateDefinitionsMap;

The module’s emails/index.ts exposes the map as emailTemplateDefinitions; its backend module contributes that property to the existing module registry. The normal compiler publishes the template and label JavaScript before startup scans them. Add files to that owning module rather than creating another global registry. Provider selection supplies the complementary sender and deployment setup.

On a successful status change, the selectors resolve the creator and current assignee from the committed task. An unassigned task produces no assignee recipient. Each email uses its own resolved reference and recipient locale. Inspect the rendered message and sender outcome; an email declaration is not itself proof of provider delivery.

Follow the configured channel

The factory preserves the declarations and the operation pipeline invokes the notification dispatcher. Email uses the template registry and provider, websocket messages reach connected clients, and FRONT_END_SUCCESS is handled by the frontend. Recipient policy and optional conditions are evaluated by the dispatcher.

Treat notifications as consequences of the business action, not as its authorization decision. A failed message is logged without turning a completed action into a rollback. For links that authorize later work, use the token-backed operation contract rather than constructing an unrelated token inside a template.

Express the state that earns the notification

The organization-member configuration uses one predicate for the pending invitation state:

Selected from organization-members.shared.resources-config.schemas.ts; surrounding module configuration is omitted.

const isPendingOrganizationMemberInvitation = ({
  currentObject,
}: {
  currentObject: Record<string, unknown>;
}): boolean =>
  currentObject.status === OrganizationMemberStatus.INVITED;

Its email declaration then uses that predicate:

Selected from organization-members.shared.resources-config.schemas.ts; surrounding module configuration is omitted.

      userNotifications: [
        {
          target: CoreUserNotificationTarget.USER_SELF,
          channel: CoreUserNotificationChannel.EMAIL,
          recipientEmailField: 'userEmail',
          condition: isPendingOrganizationMemberInvitation,
        }
      ]

The dispatcher runs the condition against post-operation function parameters before channel routing. An absent condition means the declaration is eligible; a false condition skips that notification. The same gate applies before the direct email-address path.

Respect a deliberate quiet request

The existing organization suspension operation accepts suspensionReason and notifyMembers (default true). Its email declaration uses the request, not the resulting organization’s status. Selected from the registered suspension operation, with explanatory comments omitted:

userNotifications: [
  {
    target: CoreUserNotificationTarget.ORGANIZATION_USERS,
    channel: CoreUserNotificationChannel.EMAIL,
    condition: ({ inputDto }) => (inputDto as { notifyMembers?: boolean } | undefined)?.notifyMembers !== false,
  }
]

Example request body for an authorized suspension:

{
  "suspensionReason": "Temporary administrative review",
  "notifyMembers": false
}

The operation still suspends the organization; this declaration sends no member email. Omitting the flag retains the default notification. The condition grants no suspension authority: the operation still requires its super-admin role and an eligible organization state.

These are the authored inputs. A previous version of the record is not supplied as previousObject by this contract.

Coordinate related side effects

Invitation token generation has its own condition on the operation variant. Apply the same state rule to both token generation and notification when neither should occur for an active member. Conditioning only the template would still mint an unused token; conditioning only token creation could leave an email with no meaningful acceptance link.

A predicate that throws is caught as that notification’s dispatch failure so later declarations can still be processed. Keep the condition deterministic and focused on eligibility; authorization and data mutation belong to the operation itself.

Select the address from the operation result

An email notification can declare recipientEmailField: the name of one top-level field on the committed record containing one email-address string. It is not a nested path, address array or recipient selector. The membership invitation reads userEmail:

Selected from organization-members.shared.resources-config.schemas.ts; surrounding module configuration is omitted.

      userNotifications: [
        {
          target: CoreUserNotificationTarget.USER_SELF,
          channel: CoreUserNotificationChannel.EMAIL,
          recipientEmailField: 'userEmail',
          condition: isPendingOrganizationMemberInvitation,
        }
      ]

That address takes the email-by-address route instead of recipient-user expansion. The target still participates in the notification/template identity; it does not override the explicit destination. Here USER_SELF preserves the invitation template reference, while userEmail identifies the invitee.

Supply content that does not assume a profile

The path uses application-default locale behavior because no user preferences record is available. Its base operation context and additional token context remain available, so the invitation template can render the acceptance URL. Do not assume a first name or personalized language exists merely because an address does.

The sender validates address format before network submission. Missing addresses or submission failures are logged as notification failures rather than reversing the completed business action. For critical invitation recovery, the named resend operation supplies a new token and message.

Declare the token on the operation variant

The organization-member creation variant contains this token configuration:

Selected from organization-members.shared.resources-config.schemas.ts; surrounding module configuration is omitted.

          tokenGeneration: {
            tokenType: CoreConsumableTokenTypes.ORGANIZATION_MEMBER_INVITATION,
            consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
            expiresIn: { value: 7, unit: DurationUnit.DAYS },
            relatedIdField: '_id',
            emailLinkPath: '/invitation',
            // Mint the accept token for real invites only — never for an ACTIVE direct-add.
            condition: isPendingOrganizationMemberInvitation,
          },

tokenGeneration makes the resource operation transactional. relatedIdField ties the token to the created membership and emailLinkPath selects the acceptance path. The matching notification reads userEmail and uses the same invitation-state condition. The dispatcher derives acceptUrl from the committed token rather than asking the template to mint one.

Complete the consumer side

The application must provide the matching template and acceptance route. A missing template for a token-backed producer is a fatal startup validation error. The resource and token mutation share the transaction; template lookup is a separate setup check. The acceptance action still checks token validity and the relevant business state; the existence of a link in an email is not authority on its own.

Follow the invitation into its actual template

The organization-member CREATE notification uses USER_SELF as its template identity and recipientEmailField: 'userEmail' as its destination. The resolved reference is email.organizationMembers.create.user-self. Wonder Todos registers the renderer and locale labels from:

backend-api/src/engine/email/resources/organizationMembers/
  create.user-self/
    template.tsx
    labels.en.ts

The engine email module scans resources and contributes the resulting emailTemplateDefinitions map through the backend module registry. This is the same registration path used by workspace lifecycle emails; keep one registry, with a renderer for every declared reference.

Inside the existing invitation template’s body, the dispatcher-supplied context provides acceptUrl. This selected JSX branch shows what the real renderer does with it; the surrounding body has already resolved acceptUrl, dashboardUrl, brand, labels and appName:

{acceptUrl ? (
  <PrimaryButton href={acceptUrl} brand={brand} style={{ marginTop: '24px' }}>
    {labels.buttonAcceptInvitation}
  </PrimaryButton>
) : dashboardUrl ? (
  <PrimaryButton href={dashboardUrl} brand={brand} style={{ marginTop: '24px' }}>
    {labels.buttonAcceptInvitation}
  </PrimaryButton>
) : (
  <BodyText brand={brand} style={{ marginTop: '24px' }}>
    {interpolateEmailLabel(labels.fallbackSignInAccept, { appName })}
  </BodyText>
)}

Here acceptUrl comes from context.additionalContext, not a token produced by the React component. The dashboard/sign-in branches are fallback presentation; they do not mint an invitation token or replace a working acceptance link.

Finish at the registered acceptance route

The standard router registers /invitation. AuthPage_Invitation reads the token query parameter and supplies it to Auth_Invitation. That consumer calls getInvitationInfo(token) to discover the invitation and permitted joining methods, then uses the invitation-specific acceptance flow. The password path passes invitationToken to acceptInvitation; other supported methods keep their own acceptance behavior and authentication checks.

The visible chain is therefore membership creation → committed token → additionalContext.acceptUrl → the template’s button → /invitation?token=… → invitation validation and acceptance. Inspect the rendered button URL as well as the record/token result. Retain the standard route when using this producer; replacing the frontend requires implementing that consumer contract, not merely drawing an invitation form.

Recover through the named operation

The invitation resend variant revokes existing tokens for the related membership and creates a new one. A delayed earlier email can therefore carry an unusable link. Conversely, a process can stop after commit but before provider submission, leaving valid work without a delivered message. The administrator’s resend operation is the explicit recovery path; the token transaction is not an exactly-once email outbox.

Connect operation, target and template

The restore declaration includes this actual notification definition:

userNotifications: [
  {
    target: CoreUserNotificationTarget.ORGANIZATION_USERS,
    channel: CoreUserNotificationChannel.EMAIL,
  }
]

It tells the notification pipeline whom the event is for and which channel to use. The application supplies the corresponding email template and delivery configuration. Wonder Todos keeps those templates under backend-api/src/engine/email/resources/organizations/, including separate templates where the administrator variant has a distinct reference.

Register the file under the reference the operation resolves

For restore, the operation identifier is Organization_Lifecycle_Operations.RESTORE (restore), the target is ORGANIZATION_USERS, and the resolved template reference is email.organizations.restore.organization-users. Wonder Todos supplies it from:

backend-api/src/engine/email/resources/organizations/
  restore.organization-users/
    template.tsx
    labels.en.ts

template.tsx default-exports an EmailTemplateDefinition; each locale file exports labels. The normal compiler must publish the corresponding JavaScript files before the startup scanner can load them. A source file alone is not a registered runtime template.

This is the resource-directory scan used by the existing email definitions module, with its shared options inlined:

import {
  scanEmailTemplateDirectory,
  type EmailTemplateDefinition,
} from '@wildo-ai/saas-backend-lib';

const resourceTemplates = await scanEmailTemplateDirectory<EmailTemplateDefinition>({
  importMetaUrl: import.meta.url,
  subdir: 'resources',
  keyFromPath: (relativePath) => `email.${relativePath.replace(/\//g, '.')}`,
});

Keep this scanner in backend-api/src/engine/email/email-template-definitions.ts, where resources is a sibling directory. Its map is merged into the existing emailTemplateDefinitions, alongside system templates. The engine backend module contributes that map through its emailTemplateDefinitions property; modules-registry.backend.ts collects those module maps as defaultEmailTemplateDefinitions for buildApplicationInitializationConfigFromModules. Extend this existing path rather than creating a second registry or importing the template directly in a sender.

The HTTP route uses request-deletion, but the template reference retains the internal request_deletion identifier. The variant segment also matters: a template for the tenant action does not satisfy the administrator action’s reference.

Match the message to the transition

Organization_Lifecycle_Operations.REQUEST_DELETION (request_deletion) carries the warning at the reversible mark. restore informs members when access returns. Suspension’s condition respects notifyMembers; activation targets the administrative audience. These audiences are intentional and should not all become the same generic broadcast.

Organisation category email routing can replace the member audience for mapped categories. An ORGANIZATION_USERS target remains a per-member audience, as described in workspace email settings.

Verify delivery prerequisites as well as the declaration

The startup validator reports unresolved template references and names the directory expected. That check does not itself prove an email was delivered. Exercise the operation with the configured email transport and inspect its delivery result, especially the quiet-suspension case and the deletion-request warning.

Declare the audience and channel

Wonder Todos configures both immediate feedback and colleague notifications on its operations:

Selected from todos.resources-config.ts; surrounding module configuration is omitted.

      userNotifications: [
        { target: CoreUserNotificationTarget.USER_SELF, channel: CoreUserNotificationChannel.FRONT_END_SUCCESS },
        { target: CoreUserNotificationTarget.ORGANIZATION_USERS, channel: CoreUserNotificationChannel.WEBSOCKET },
      ],

The dispatcher resolves the target and sends the websocket notification. WebSocketEventBridge turns resource-notification payloads into typed notification events; NotificationContext applies the frontend presentation and labels. Use the standard bridge and notification provider in the application shell rather than adding a second independent toast listener.

Separate messages from data synchronization

A user-facing message tells someone what happened. Resource update frames tell subscribed views when to refresh. Turning off the personal notification centre does not stop those refresh frames, which are necessary to keep application data current.

This path reaches active connected clients. It is not by itself a durable offline inbox, mobile push delivery or read receipt. If the product needs a persisted notification record, author that record and its lifecycle explicitly instead of treating a websocket frame as storage.

Reach the responsible organization roles

Organization billing, security, user-management and administrative targets default to owners and administrators when userRoles is omitted or empty. An explicit list selects those roles instead. Delivery uses the authenticated organization-role subscriptions; a role in another organization does not grant access to this message.

Use the standard live-update consumers

The backend websocket service and notification dispatcher publish resource events to their applicable rooms. The frontend shell installs WebSocketEventBridge; resource-manager consumers also use their dedicated bridge for synchronization and authoritative refetch decisions.

The general bridge maps an update into refresh context:

Selected from WebSocketEventBridge.tsx; surrounding module configuration is omitted.

    const unsubUpdated = on<WS_ResourceUpdatedPayload>(
      CoreWebSocketEvent.RESOURCE_UPDATED,
      (payload) => {
        // RESOURCE_UPDATED always triggers generic refresh fan-out here so
        // non-RMM consumers still invalidate list/read surfaces. Resource-room
        // sync replay and authoritative refetch decisions remain owned by
        // RMMWebSocketBridge.
        emitRefreshPayloads({
          resourceType: payload.resourceType,
          resourceIds: payload.deliveryTarget === WebSocketResourceDeliveryTarget.SCOPE_ROOM_NOTIFICATION
            ? payload.affectedIds ?? []
            : [payload.resourceId],
          contextResourceIdentifiers: payload.contextResourceIdentifiers ?? {},
          shouldEmitReadRefresh: payload.deliveryTarget === WebSocketResourceDeliveryTarget.SCOPE_ROOM_NOTIFICATION
            ? (payload.affectedIds?.length ?? 0) > 0
            : Boolean(payload.resourceId),
        });
      }
    );

The delivery target determines whether the payload identifies affected IDs in a scope room or one resource. Context identifiers accompany the refresh so a consumer can address the right view. A custom data screen needs to consume the shared refresh events or resource-manager contract; merely opening a socket is not enough.

Subscribe a custom list and release its listener

For a custom list outside ResourceMutationManager (RMM) ownership, invalidate the list’s own authorized query when its matching refresh event arrives. This complete illustrative hook uses the public event bus. Its caller supplies the active operation context and a stable, synchronous cache-invalidation callback:

import { useEffect } from 'react';
import {
  FrontendEvents,
  useEventBus,
  type FrontendEventPayloads,
} from '@wildo-ai/saas-frontend-lib';

type RefreshContext = FrontendEventPayloads[FrontendEvents.RESOURCE_REFRESH];

export function useCustomListRefresh(
  context: RefreshContext,
  invalidate: () => void,
) {
  const { on } = useEventBus();
  useEffect(() => {
    const off = on(FrontendEvents.RESOURCE_REFRESH, invalidate, (event) => {
      const sameOperation = event.resourceType === context.resourceType
        && event.operationIdentifier === context.operationIdentifier
        && event.variantType === context.variantType
        && event.variantKey === context.variantKey
        && !!event.isBulkOperation === !!context.isBulkOperation
        && !!event.isOperationDefault === !!context.isOperationDefault;
      const expected = context.contextResourceIdentifiers;
      const actual = event.contextResourceIdentifiers;
      return sameOperation
        && Object.keys(expected).length === Object.keys(actual).length
        && Object.entries(expected).every(([key, value]) => actual[key] === value);
    });
    return off;
  }, [on, context, invalidate]);
}

Use the normalized context of the active list, including its organization/parent identifiers; do not match only the resource name across workspaces. Call this hook unconditionally in the mounted custom list under the normal event-bus provider. Its callback marks that list query stale, and the query’s existing reader, loading and error handling fetch the authorized result. Context changes release the old listener; unmount releases the current one.

This consumer does not create a socket room subscription. The standard shell/socket services must already be connected and subscribed to the applicable authorized scope. A custom resource-room subscription needs its corresponding join and leave lifecycle as well. For RMM-managed screens, retain RMMWebSocketBridge and its synchronization/refetch rules instead of installing a second state owner.

Check with two connected views in the same scope: an update should invalidate the matching custom query, a different scope should not, and leaving the view should release its listener. Personal message preferences do not disable this data-refresh contract.

Keep the backend authoritative

A frame signals that data changed; the normal read path still supplies the authorized data. Do not treat a notification payload as permission to reveal every field or assume it replaces a complete refetch. Deletion, updates and active editing have distinct event meanings.

Verify the view’s subscription and refresh behavior for its actual scope. The transport does not establish that every custom screen will refresh without being connected to these consumers.

Declare the query and its scope

Wonder Todos owns this badge in the tasks-manager module:

Selected from notification-badges.tasks-manager.ts; surrounding module configuration is omitted.

export const tasksManagerNotificationBadgeDefinitions: NotificationBadgeDefinition[] = [
  {
    identifier: USER_SELF_INCOMPLETE_TODOS_BADGE_IDENTIFIER,
    scope: ResourcePrimaryScope.USER_SELF,
    source: {
      kind: NotificationBadgeSourceKind.DERIVED_QUERY,
      resourceType: TasksManager_ResourceType.TODOS,
      filter: { status: { $nin: [Todos_Status.COMPLETED, Todos_Status.CANCELLED] } },
      scopeField: 'assignedToUserId',
    },
    display: {
      mode: NotificationBadgeDisplayMode.COUNT,
      tone: IndicatorVariant.INFO,
      pulse: NotificationBadgePulse.ON_INCREASE,
    },
  },
];

Register the definition through the module’s notificationBadgeDefinitions; the shared registry aggregates it for backend and frontend. The navigation item names its key through notificationBadgeRef. The key combines scope and identifier, keeping user and organization badges distinct.

Let the data own the count

resourceType identifies the counted collection, filter states which records qualify and scopeField binds the count to the current badge owner. The backend recomputes on source mutations and connection initialization. For explicit multi-ID reassignment through the shared core path, Wildo captures prior owners before mutation and recomputes both prior and current owners after commit. Unassignment also refreshes the owner losing those records. The captured values belong to the successful transaction attempt; they do not change the object passed to single-row hooks. Arbitrary filter mutations and custom paths that bypass the core are outside that capture contract.

Use the shared mutation path so those hooks run. Direct database writes do not carry the operation’s notification behavior. For a quantity that is genuinely a stored event counter, such as unread events acknowledged separately from their source records, choose EVENT_COUNTER instead.

Register the counter and its scoped identity

Application example: count actions completed by the current user until that user acknowledges them. This is an authored counter, not a built-in producer. Put this definition in the owning shared module:

import {
  buildNotificationBadgeKey,
  NotificationBadgeDisplayMode,
  NotificationBadgePulse,
  NotificationBadgeSourceKind,
  ResourcePrimaryScope,
  type NotificationBadgeDefinition,
} from '@wildo-ai/saas-models';
import { IndicatorVariant } from '@wildo-ai/presets-components-models';

export const completedActionsBadge: NotificationBadgeDefinition = {
  identifier: 'completed_actions',
  scope: ResourcePrimaryScope.USER_SELF,
  source: { kind: NotificationBadgeSourceKind.EVENT_COUNTER },
  display: {
    mode: NotificationBadgeDisplayMode.COUNT,
    tone: IndicatorVariant.NEUTRAL,
    pulse: NotificationBadgePulse.NONE,
  },
};
export const completedActionsBadgeRef = buildNotificationBadgeKey(
  completedActionsBadge.scope, completedActionsBadge.identifier,
);

Add the definition to the module’s notificationBadgeDefinitions. A navigation item uses completedActionsBadgeRef as its notificationBadgeRef; badge presentation connects registration to the visible consumer. The identifier alone is not the scoped key.

Move it from the operations that own those events

These are the complete badge-operation entries to place on the two existing resource operations. Import NotificationBadgeOperation from @wildo-ai/saas-models and the key from the shared module above:

// On the operation that completes one action for its initiator:
notificationBadgeOperations: [{
  badgeRef: completedActionsBadgeRef,
  operation: NotificationBadgeOperation.INCREMENT,
}],

// On the operation through which that user acknowledges the count:
notificationBadgeOperations: [{
  badgeRef: completedActionsBadgeRef,
  operation: NotificationBadgeOperation.RESET,
}],

The dispatcher reads the scope from the registered definition, then takes its owner from the operation’s initiatorIds. A user-scoped definition uses the initiator’s userId; an organization-scoped one uses their organizationId. Missing identity at that scope means no counter update. The affected record’s assignee is not a recipient selector for this declaration.

The authoring entry contains only badgeRef and operation: the dispatcher supplies the value 1. The lower-level service’s numeric argument does not add a custom amount or recipient field to this declaration.

Check the acknowledgement behavior

Starting at zero, two successful completion operations by the same user produce two; their acknowledgement operation resets it to zero. The backend pushes the updated count to that owner’s scope, and the badge hook updates its registered consumer. A different user has a different counter.

Relative changes use guarded storage arithmetic; reset is an absolute write, so a concurrent reset and increment follow their write ordering. The application decides what acknowledgement means and wires every producer. If business records already contain the truth—such as unfinished assignments—use a derived count instead of maintaining a second unread state.

Register the meaning, then expose it in navigation

Wonder Todos already defines the incomplete-assignment badge in its tasks-manager shared module. This complete definition uses the module’s TasksManager_ResourceType and Todos_Status constants; badge enums and types come from @wildo-ai/saas-models, and IndicatorVariant comes from @wildo-ai/presets-components-models:

export const tasksManagerNotificationBadgeDefinitions: NotificationBadgeDefinition[] = [
  {
    identifier: USER_SELF_INCOMPLETE_TODOS_BADGE_IDENTIFIER,
    scope: ResourcePrimaryScope.USER_SELF,
    source: {
      kind: NotificationBadgeSourceKind.DERIVED_QUERY,
      resourceType: TasksManager_ResourceType.TODOS,
      filter: { status: { $nin: [Todos_Status.COMPLETED, Todos_Status.CANCELLED] } },
      scopeField: 'assignedToUserId',
    },
    display: {
      mode: NotificationBadgeDisplayMode.COUNT,
      tone: IndicatorVariant.INFO,
      pulse: NotificationBadgePulse.ON_INCREASE,
    },
  },
];

The same file creates its key with buildNotificationBadgeKey(ResourcePrimaryScope.USER_SELF, USER_SELF_INCOMPLETE_TODOS_BADGE_IDENTIFIER). The tasks-manager SharedSaaSModule registers the array as notificationBadgeDefinitions: tasksManagerNotificationBadgeDefinitions; its shared registry makes the definition available to backend calculation and frontend lookup.

The existing frontend module places this complete item in its sidebar section’s children array:

{
  kind: LauncherItemTargetKind.RESOURCE_OPERATION,
  resourceType: TasksManager_ResourceType.TODOS,
  operation: CoreResourceOperation.LIST,
  notificationBadgeRef: USER_SELF_INCOMPLETE_TODOS_BADGE_REF,
},

LauncherItemTargetKind is imported from @wildo-ai/saas-frontend-lib/companion, CoreResourceOperation from @wildo-ai/saas-models, and the resource and badge constants from @wonder-todos/shared-lib. The normal resource-operation item derives its label from the application’s registered resource labels.

Keep a custom consumer accessible

For a custom navigation surface inside the standard application providers, use the same registered key and supply the already translated navigation label. This complete illustrative consumer accepts both from its parent:

import { NavigationItemBadge } from '@wildo-ai/saas-frontend-lib';

export function NavigationAttention({ badgeRef, label }: {
  badgeRef: string;
  label: string;
}) {
  return (
    <NavigationItemBadge
      notificationBadgeRef={badgeRef}
      label={label}
    />
  );
}

The component finds the definition by scoped identity, subscribes through useNotificationBadges, and passes count, tone, pulse and accessible label to the standard indicator. A missing definition renders no badge; a missing label exposes an unresolved key rather than inventing readable words.

COUNT shows the number up to the configured display cap; DOT shows positive activity without its number; NONE suppresses the indicator. The standard indicator also hides non-positive counts. Reassigning a task changes the underlying derived count; presentation decides how that new value asks for attention.

Keep motion in the theme

useNotificationBadges resolves the pulse trigger and its timed window. The replaceable NotificationIndicator slot takes the tone and pulse result; the active theme supplies the attention recipe. Do not hard-code a competing animation into each navigation item.

Choose ON_INCREASE for a transient signal, WHILE_ACTIVE for continuing attention or NONE when the number is sufficient. These settings do not change which records are counted or the operation that clears an event counter. Verify the chosen policy in the actual navigation surface and theme.

Store choices through the preference resource

The user’s self-preferences record contains notification channel switches. The operation dispatcher loads them with recipient context and applies its delivery decision to personal email. The shared preference predicate also defines SMS and push switches; those operation-dispatch channels do not yet have sending implementations. The relevant gate is:

Selected from notifications-dispatcher.backend.service.ts; surrounding module configuration is omitted.

  private recipientAcceptsNotificationChannel(
    notification: UserNotificationDefinition,
    recipientUserContext: { notificationChannelPreferences?: UserPreferences_Notifications } | undefined,
  ): boolean {
    if (notification.alwaysDeliver === true) return true;
    if (!userNotificationTargetIsSuppressibleByRecipientPreference(notification.target)) return true;

    const preferences = recipientUserContext?.notificationChannelPreferences;
    if (!preferences) return true;

    switch (notification.channel) {
      case CoreUserNotificationChannel.EMAIL:
        return preferences.email !== false;
      case CoreUserNotificationChannel.SMS:
        return preferences.sms !== false;
      case CoreUserNotificationChannel.PUSH:
        return preferences.push !== false;
      default:
        // WEBSOCKET and FRONT_END_SUCCESS carry no switch of their own. The `inApp` preference
        // governs the notification CENTRE, which is a frontend surface — `NotificationContext`
        // honours it there, because suppressing the socket frame would also suppress the live
        // UI updates that ride the same channel.
        return true;
    }
  }

An absent preference record preserves delivery. alwaysDeliver explicitly bypasses personal suppression, and role-addressed targets are not treated as optional personal subscriptions. Use that distinction for a billing or security responsibility; do not mark every product message mandatory.

Keep in-app presentation separate

NotificationContext applies inApp to optional personal server messages before displaying a toast, notification-centre entry or celebration. Declarative frames carry their recipient target and alwaysDeliver flag through WebSocketEventBridge, so required notices and responsibility-addressed messages stay visible.

Local save confirmations keep their own behavior. The same websocket frame can still refresh lists and records even when its personal message is hidden.

Preference filtering does not implement a transport. Use the implemented email and in-app paths for this operation-notification flow. Direct email-by-address has no user preference record and follows its own delivery contract. Author the recipient target and obligation carefully before selecting a suppression policy.

Configure addresses and category switches together

This illustrative emailNotifications value routes two categories and leaves the others enabled with a default address:

{
  "emailNotifications": {
    "defaultEmailAddress": "operations@example.com",
    "billingAddress": "finance@example.com",
    "securityAddress": "security@example.com",
    "billing": true,
    "security": true,
    "administrative": true,
    "usersManagement": true
  }
}

The organisation notification resource is seeded during organisation creation. Update its settings through the generated organisation-scoped resource operation; no custom dispatcher is needed for these standard categories.

Routing still needs a registered email template and a configured delivery provider. Follow the template registration example and transactional email setup for those prerequisites. Saving a destination address does not supply either one or prove message delivery.

Understand delivery precedence

For an email with a mapped organisation target, the dispatcher checks the category switch first. false suppresses the category, including ordinary member fan-out. Otherwise it uses the category address, then defaultEmailAddress, then the existing member-target resolution when neither address is set.

ORGANIZATION_USERS intentionally remains member fan-out. These settings route email; they do not redirect every channel or every notification target.

Keep fallback behavior visible to operators

A missing settings record or a failed settings read falls back to member delivery. It does not silently drop the message. If a customer requires all mail to remain in a shared inbox, monitor failed settings reads as part of operating that requirement.

The category is derived from the notification target. Declaring another category flag on each notification would create a second answer that could disagree with the routing policy.