Give each customer a billing home
A billing account connects an organization or person to its provider customer and financial activity. Subscriptions, invoices, usage and credits can then refer to the same customer without mixing personal and workspace purchases.
Example — Keep a team’s purchase with the team
An organization has its own billing account. A member’s separately enabled personal subscription belongs to a different account.
For engineers
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.