> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get Billing Status > Read the calling tenant's Recurso Cloud billing lifecycle: status, plan tier and trial window. Returns where the calling tenant stands with Recurso Cloud itself — not your customers' billing, but your own account with Recurso: whether you are trialing, active, past due or canceled, which plan tier you are on, when the trial ends and how many whole days remain. The dashboard uses it to show the trial banner. It is read-only; there is no self-serve upgrade endpoint yet. For the tenant record itself see [Get Account](/api-reference/account/get); for the plans you can move to see [List Cloud Plans](/api-reference/billing/list-plans). Self-hosted deployments still answer, with whatever `billing_status` and `plan_tier` the tenant row carries. ## Parameters This endpoint takes no parameters. ## Example Request ```bash theme={null} curl https://api.recurso.dev/v1/billing/status \ -H "Authorization: Bearer $API_KEY" ``` ## Response The object is returned bare (no `data` envelope). ```json theme={null} { "billing_status": "trialing", "plan_tier": "trial", "trial_ends_at": "2026-09-18T00:00:00Z", "trial_days_left": 14, "trial_expired": false } ``` ## Fields | Field | Type | Description | | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `billing_status` | string | `trialing`, `active`, `past_due` or `canceled` | | `plan_tier` | string | `trial` (set at sign-up) or `free` (the column default). Paid tiers are not yet assigned to tenants; the `cloud` / `enterprise` keys from [List Cloud Plans](/api-reference/billing/list-plans) are catalog entries, not values this field takes today | | `trial_ends_at` | string (RFC 3339) | End of the trial window. Omitted when the tenant is not on a trial | | `trial_days_left` | integer | Whole days until `trial_ends_at`, rounding a partial day up. `0` when there is no trial or it has ended | | `trial_expired` | boolean | `true` only when `billing_status` is `trialing` and `trial_ends_at` is in the past | ## Errors | Status | Code | When | Fix | | ------ | ---------------- | ------------------------------------ | ------------------------------------- | | `401` | `unauthorized` | Missing or invalid API key / session | Send `Authorization: Bearer $API_KEY` | | `500` | `internal_error` | Loading the tenant account failed | Retry; contact support if it persists | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /v1/billing/status openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/billing/status: get: tags: - Account summary: Get the tenant's managed-cloud billing/trial status description: > Returns the tenant's billing lifecycle: status (trialing/active/ past_due/canceled), plan tier, trial end, days left, and whether the trial has expired. Read-only in this increment. operationId: getBillingStatus responses: '200': description: Billing status. content: application/json: schema: type: object properties: billing_status: type: string enum: - trialing - active - past_due - canceled plan_tier: type: string trial_ends_at: type: string format: date-time trial_days_left: type: integer trial_expired: type: boolean '401': $ref: '#/components/responses/Unauthorized' components: responses: Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````