Skip to main content
GET /v1/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

​
status
string
The billing account state: ACTIVE, PAST_DUE, UNPAID, or SUSPENDED.
​
feature_mode
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
​
grace_until
string | null
ISO 8601 timestamp for when the current grace period ends, or null if the account is in good standing.
​
banner
string | null
A human-readable message describing the required action, or null when no action is needed.
curl https://api.truthlocks.com/v1/billing/status \
  -H "X-API-Key: tl_live_..."

{
  "status": "ACTIVE",
  "feature_mode": "NORMAL",
  "grace_until": null,
  "banner": null
}

​
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.
const res = await fetch("https://api.truthlocks.com/v1/billing/status", {
  headers: { "X-API-Key": "tl_live_..." },
});
const { feature_mode, grace_until } = await res.json();

if (feature_mode !== "NORMAL") {
  showPaymentBanner(feature_mode, grace_until);
}

​
Grace period timing

The default grace windows for the Standard contract mode are:
TransitionGrace windowNotifications
NORMAL → DEGRADED7 daysReminders at T+24h, T+48h, T+72h
DEGRADED → RESTRICTED14 daysReminders at T+24h, T+48h, T+72h
RESTRICTED → SUSPENDEDImmediateFinal suspension notice
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.