Skip to main content

Current billing state

Use Current Billing State when an application needs to show the user's actual billing status. It is the authoritative read model for effective plans and billing mode; it is not a replacement for wallet balances or provider subscription lifecycle operations.

Endpoints​

  • Frontends with a platform bearer token call GET /api/v1/billing-state. Account and user identity come only from verified token claims; selectors are intentionally unavailable.
  • Backends with service auth call GET /mgt/v1/billing-accounts/{billing_account_id}/billing-state. Omit user selectors for the account view, or provide exactly one of user_id and billing_user_id for a user-effective view.

Both endpoints use the same resolver and response schema. They are read-only: missing accounts, users, plans, and assignments are never provisioned by these requests. A valid account without an effective base plan returns base: null.

Response boundaries​

The response contains:

  • as_of: the single server-selected instant used for all mutable facts;
  • view_scope: account or user;
  • the effective base, add-ons, and promotions;
  • billing_mode and its assignment, plan, realm, or system source;
  • relevant provider subscription lifecycle facts;
  • next_change_at, an advisory earliest known refresh boundary.

For a complete billing UI, read Current Billing State alongside GET /api/v1/wallet/balance. Wallet is authoritative for spendable balance; Current Billing State is authoritative for commercial configuration.

Effective-plan rules​

In a user view, a user-scoped base overrides an account-scoped base. Within the same scope, higher plan priority wins, followed by the latest assignment start and assignment ID. Add-ons and promotions are returned independently and do not change billing mode.

Billing mode comes only from the selected effective base, in this order:

  1. assignment metadata.billing.period.billing_mode;
  2. plan metadata.billing_defaults.period.billing_mode;
  3. realm metadata.billing_defaults.period.billing_mode;
  4. system default prepaid.

Subscription state never makes a plan effective by itself. The normalized plan assignment remains the runtime source of truth.