> ## Documentation Index > Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt > Use this file to discover all available pages before exploring further. # Get billing status > Returns the current billing state, feature mode, and grace period for the authenticated tenant. ```http theme={null} 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 The billing account state: `ACTIVE`, `PAST_DUE`, `UNPAID`, or `SUSPENDED`. 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 ISO 8601 timestamp for when the current grace period ends, or `null` if the account is in good standing. 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. ```javascript theme={null} 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: | Transition | Grace window | Notifications | | :--------------------- | :----------- | :------------------------------- | | NORMAL → DEGRADED | 7 days | Reminders at T+24h, T+48h, T+72h | | DEGRADED → RESTRICTED | 14 days | Reminders at T+24h, T+48h, T+72h | | RESTRICTED → SUSPENDED | Immediate | Final 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](/billing/overview#contract-modes) for details. See [payment failures and grace periods](/billing/overview#payment-failures-and-grace-periods) for a full breakdown of the graduated access workflow. ## OpenAPI ````yaml mint-openapi.yaml GET /v1/billing/status openapi: 3.0.3 info: title: Truthlocks API description: > Truthlocks is a universal verification infrastructure for documents, credentials, and digital assets. This specification defines the canonical API for interacting with Truthlocks services. ## Base URLs - **Production**: `https://api.truthlocks.com` - **Sandbox**: `https://sandbox-api.truthlocks.com` ## Authentication - **API Keys**: Use `X-API-Key` header for machine-to-machine operations - **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated operations ## Tenant Identity In production, tenant identity is derived from the authenticated context (API key or JWT). The `X-Tenant-ID` header is ignored in production to prevent spoofing. version: 1.0.0 contact: name: Truthlocks Support url: https://truthlocks.com/support email: support@truthlocks.com servers: - url: https://api.truthlocks.com description: Production API - url: https://sandbox-api.truthlocks.com description: Sandbox Environment security: - APIKey: [] tags: - name: Authentication description: API key and token management - name: Issuers description: Issuer registration and trust management - name: Keys description: Cryptographic key management for issuers - name: Attestations description: Attestation lifecycle (mint, revoke, supersede) - name: Verification description: Attestation verification and proof bundles - name: Governance description: Issuer governance workflows (admin only) - name: Identity description: Organization, user, and role management - name: Audit description: Audit event queries - name: Platform description: Platform administration (super admin only) - name: Platform Review description: Staff review workflows for issuer applications - name: Tenant Console description: Tenant profile and lifecycle endpoints - name: Health description: Service health and readiness endpoints - name: Risk description: Risk signal ingestion and fraud detection - name: Risk Enforcement description: Risk enforcement actions — block, challenge, quarantine, and configuration - name: Billing description: Billing, subscription, and addon management - name: Machine Identity description: >- Machine Agent Identity Protocol (MAIP) — agent registration, sessions, trust, witness, compliance, orchestration, and observability externalDocs: description: Transparency read-only API (separate service spec) url: >- https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml paths: /v1/billing/status: get: tags: - Billing summary: Get billing status description: >- Returns the billing status, current plan, and feature flags for the authenticated tenant. operationId: billing.status responses: '200': description: Billing status content: application/json: schema: type: object properties: plan: type: string status: type: string trial_ends_at: type: string nullable: true '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - APIKey: [] components: schemas: ErrorEnvelope: type: object required: - code - message - http_status properties: code: type: string description: Machine-readable error code enum: - AUTH_REQUIRED - AUTH_INVALID - PERMISSION_DENIED - TENANT_IDENTITY_UNVERIFIED - NOT_FOUND - VALIDATION_ERROR - CONFLICT - PAYLOAD_TOO_LARGE - RATE_LIMIT_EXCEEDED - QUOTA_EXCEEDED - SERVICE_UNAVAILABLE - INTERNAL_ERROR message: type: string description: Human-readable error message http_status: type: integer description: HTTP status code retry_after_ms: type: integer description: Milliseconds to wait before retrying (for rate limits) details: type: object description: Additional error context example: code: AUTH_REQUIRED message: Authentication required http_status: 401 securitySchemes: APIKey: type: apiKey in: header name: X-API-Key description: API key for machine-to-machine authentication ````