No plan assigned: the app can still issue tokens, but no
limits claim is
added. Retired plan assigned: token issuance is blocked.What Billing Controls
Billing is tied to plan assignment on a tenant app.- free plans can be assigned directly
- paid plans use the payment provider flow
- changing plans may either assign immediately or create a billing session, depending on the current app state
Assigning Or Changing A Plan
Plan changes are initiated from the dashboard and applied to a specific app.Backend Flow
- load the target plan
- validate that the target plan can be assigned
- load the app’s current plan and subscription state
- decide whether the change is direct or requires billing
Free And Paid Plan Behavior
Free Plans
Free plans can be assigned directly without a checkout session. If the app already has a paid subscription, the backend cancels that subscription and updates the app state before completing the free-plan assignment.Paid Plans
Paid plans use the payment provider flow.- if the app already has an active paid subscription, the backend requests a plan change on that subscription
- if the app has no active paid subscription, the backend creates a checkout session
- the final assignment is completed after the billing flow succeeds
One Free Plan Rule
The current domain logic allows only one app with a free plan per tenant. If a tenant already has another app on a free plan, assigning a free plan to a second app fails.Subscription Status
The billing flow tracks subscription status on the app.| Status | Description |
|---|---|
| Pending | Billing setup has started but is not complete yet. |
| Active | The subscription is active. |
| OnHold | Payment method or billing action is required. |
| Failed | The billing flow failed. |
| Cancelled | The subscription was cancelled. |
| Expired | The subscription expired. |
Treat subscription management as a separate step from enabling, disabling, or
deleting an app.
Plan Status Rules
The backend treats plan status differently depending on the operation.Activeplans can be assignedDraftplans cannot be assignedArchivedplans cannot be assigned to a new appRetiredplans block token issuance for apps that still use them
Developer Notes
For setup and troubleshooting, these are the most important rules:- assign a usable plan if you need the
limitsclaim (measured in Document Units) - keep only one free-plan app per tenant
- expect billing flow only for paid plans
- if a paid app becomes
OnHold, billing action is required before normal changes continue