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, and includes the wallet amounts needed for a current billing overview. It does not replace the full wallet breakdown 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 server-selected logical evaluation time shared by time-dependent plan, subscription, and wallet calculations;
  • 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;
  • wallet_balance, containing canonical available_balance and outstanding_balance amounts for a user view, or null for an account view;
  • next_change_at, an advisory earliest known refresh boundary.

The effective state and wallet summary use the same as_of as their logical evaluation boundary. It is not an audit snapshot or a spend-authorization guarantee; concurrent commits may be observed under the normal request database isolation. Gate remains authoritative for spend authorization. A user with no wallet activity receives a non-null summary with zero amounts. A wallet read failure fails the complete user-scoped request; null is reserved for an account view, where no single user wallet can be inferred.

For a normal “current plan and balance” UI, read only Current Billing State. Call GET /api/v1/wallet/balance when the UI or a support workflow also needs grant composition, conversion metadata, grant windows, or other wallet details. The full Wallet endpoint remains the independent authoritative breakdown.

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.