Skip to main content
GET
Get billing status
Returns your tenant’s current billing health. Use this endpoint in your integration to detect payment issues early and surface prompts to your users before access is restricted. When all payments are current, feature_mode is NORMAL and grace_until is null. If a payment fails, the account enters a graduated access workflow — Degraded, Restricted, then Suspended — with a grace period at each stage.

Response

string
The billing account state: ACTIVE, PAST_DUE, UNPAID, or SUSPENDED.
string
The current feature capability level:
  • NORMAL — all features available
  • DEGRADED — payment failed; all features still work during the grace period
  • RESTRICTED — grace period running out; write operations (minting, key creation) are disabled
  • SUSPENDED — grace period expired; all API access is disabled until payment is resolved
string | null
ISO 8601 timestamp for when the current grace period ends, or null if the account is in good standing.
string | null
A human-readable message describing the required action, or null when no action is needed.

When to use this endpoint

Use GET /v1/billing/status to:
  • Surface payment prompts — check feature_mode on app startup or login and show a banner when the value is anything other than NORMAL.
  • Guard write operations — before minting or creating keys, verify that feature_mode is not RESTRICTED or SUSPENDED.
  • Track grace deadlines — read grace_until to show your users exactly how long they have to resolve a payment issue.

Grace period timing

The default grace windows for the Standard contract mode are: Enterprise contracts add 14 extra days to each window. Government contracts use a fixed 90-day grace period with no automatic suspension. See contract modes for details.
See payment failures and grace periods for a full breakdown of the graduated access workflow.

Authorizations

X-API-Key
string
header
required

API key for machine-to-machine authentication

Response

Billing status

plan
string
status
string
trial_ends_at
string | null