Billing workspaces
A billing workspace is the isolation boundary for an organization in one environment. Plans, customers, subscriptions, API keys, transactions, provider connections, and events all belong to a workspace.
Each organization has at most one Sandbox workspace and one Production workspace. Data is never selected globally; every billing operation resolves one workspace first.
Billing workspaces are provisioned only by explicit setup or mutation flows. Read requests never create workspaces or seed catalog data. If an environment has not been configured, billing management GET routes return 404 with code: "WORKSPACE_NOT_FOUND".
New organizations provision their Sandbox workspace during the organization-creation request. Older organizations and uninitialized Production environments are sent to an explicit dashboard setup screen. Sandbox setup can import the legacy catalog; Production setup creates an empty environment that receives data only through deliberate configuration or promotion.
Operators and customers
Usagey distinguishes two identities:
- Operators are Usagey users who administer an organization.
- Customers are records your organization bills.
Customers may have an external ID and email from your application, but they do not need a Usagey operator account.
Access control
Organization owners and admins can mutate billing configuration. Lower roles can receive read-only visibility where the dashboard permits it. Platform admins remain separate from organization administration.
Public usage calls establish transaction-local tenant context before accessing customer, entitlement, credit, usage, or idempotency data. Authenticated catalog, customer, and subscription operations use the same boundary with the signed-in operator as the actor, including plans, plan entitlements, features, credit systems, credit packs, default-plan seeding, customer records, manual entitlement overrides, subscriptions, and plan-change previews.
Customer self-serve portal summaries, subscriptions, balances, usage, transactions, invoices, receipts, and lifecycle operations establish the same workspace boundary with the authenticated billable customer as the actor. Invoice aggregation and document lookup also include the customer ID in the database query; filtering does not happen only after records are loaded. Provider activity shown in the portal is limited to external subscription and transaction identifiers that belong to that customer.
A portal customer cannot use an operator or API-key context to cross an organization, environment, or customer boundary. Portal authentication resolves only the customer identity before tenant context is established; detailed billing state is loaded afterward inside the customer transaction.
Authenticated transaction APIs use that operator boundary for lists, details, receipts, manual imports, refunds, and refund retries. V2 billing-domain tables enforce the same workspace boundary with forced PostgreSQL row-level security. Relation-backed records such as plan assignments, credit balances, entitlement overrides, and settlement allocations validate every parent workspace in their policies.
Provider connection APIs and the Provider Settings dashboard read and update credentials through the operator boundary. Sandbox and Production secrets remain separate, and partial settings updates preserve encrypted credentials unless a replacement value is explicitly supplied.
Provider webhook handlers use a narrow global reference lookup only to locate the candidate workspace connection. Once the signature is verified, all webhook persistence and reconciliation runs in that workspace under an audited SYSTEM tenant context. Invalid signatures cannot mutate billing state, and matched failures remain visible in webhook and developer-event diagnostics.
Public API-key authentication follows the same two-stage pattern. A named audited discovery transaction resolves the key and workspace, then key migration metadata, last-used telemetry, entitlement checks, idempotency records, usage, and developer events execute under that API key's tenant context.
Developer-event history, webhook diagnostics, and dashboard event summaries use the operator tenant boundary. SSE authorization is checked in a short workspace transaction before the long-lived stream opens; no database transaction remains open for the lifetime of the connection.
Dashboard overview, catalog, customer, subscription, transaction, usage, revenue, analytics, settings, and onboarding queries also run inside the selected operator tenant transaction. Analytics and operational exports receive the same transaction-bound database client, so changing an export format or grouping cannot bypass workspace isolation.
Invoice email generation loads the invoice under operator tenant context, releases the database transaction before calling the email provider, and records issuance metadata in a second tenant transaction. Billing API-key lists and dashboard views expose only key fingerprints; raw secrets are returned once when a new key is created.
Scheduled internal renewals, invoice issuance, threshold settlement, and compliance retention use an explicit SYSTEM actor with a recorded job reason. The scheduler may discover candidate workspaces globally, but each workspace's billing reads and writes execute only after its tenant context is established. Provider settlement collection uses the initiating operator's idempotency transaction so allocation, refund reconciliation, and audit events cannot cross workspace boundaries.
Provider-managed renewal discovery returns only workspace identity fields. Subscription records, provider connections, plans, optimistic claims, local activation, failure state, and developer events are handled after an audited workspace SYSTEM context is established. Provider network calls occur between short claim and result transactions, so third-party latency does not hold database locks.
Customer portability and deletion operations require an authenticated operator transaction. Export snapshots and their audit events share one workspace boundary; deletion audit records and the cascading customer deletion commit atomically. Billing-action previews use the same operator-scoped reporting client as invoices and analytics.
Some operations must identify a workspace before an operator, customer, or workspace-scoped system context can be constructed. Usagey handles these through a dedicated audited system-discovery transaction. It is limited to workspace candidate enumeration, authenticated workspace bootstrap, customer-portal identity resolution, explicit workspace provisioning, environment promotion, provider webhook correlation, platform economics snapshots, and credential migration. A non-empty reason is mandatory.
Workspace-scoped system jobs can access only their selected workspace. The broader discovery predicate applies only when the transaction deliberately has no selected workspace. This prevents a webhook, renewal, retention, or invoice job from using its SYSTEM actor to read another tenant accidentally.
Workspace billing actions, retention cleanup, and internal renewal helpers do not open an unrestricted fallback transaction. Their callers must provide a tenant context or an already tenant-bound transaction client, so missing authorization context fails before billing data is read.
Analytics, invoice reporting, exports, and provider settlement operations follow the same rule. Their domain helpers require the selected workspace transaction instead of accepting an optional client that could fall back to unrestricted Prisma access.
The organization-level Usagey commercial control plane remains separate from customer billing-workspace policies, but it now has its own forced RLS boundary. Account counters, allowances, notifications, economics snapshots, and Enterprise onboarding are limited to the selected organization or an explicit audited control-plane transaction. Global infrastructure cost inputs require an audited transaction with no selected organization or workspace. Meter events additionally verify that any referenced billing workspace belongs to the recorded organization.
Sandbox promotion copies catalog structure, features, plans, assignments, and pricing tiers in one idempotent transaction. It does not copy provider connections or credentials. Production providers must be configured and verified independently before live checkout or webhook processing.