Get Billing Status

GET

billing

status

Get the tenant's managed-cloud billing/trial status

curl --request GET \
  --url https://billing.example.com/v1/billing/status \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/billing/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/billing/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/billing/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/billing/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "billing_status": "trialing",
  "plan_tier": "<string>",
  "trial_ends_at": "2023-11-07T05:31:56Z",
  "trial_days_left": 123,
  "trial_expired": true
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

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; for the plans you can move to see List Cloud 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

curl https://api.recurso.dev/v1/billing/status \
  -H "Authorization: Bearer $API_KEY"

Response

The object is returned bare (no data envelope).

{
  "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 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.

Authorizations

Authorization

string

header

required

Tenant API key obtained from POST /auth/register or POST /v1/developer/keys.

Response

Billing status.

billing_status

enum<string>

Available options:

trialing,

active,

past_due,

canceled

plan_tier

string

trial_ends_at

string<date-time>

trial_days_left

integer

trial_expired

boolean

Get the tenant's managed-cloud billing/trial status

curl --request GET \
  --url https://billing.example.com/v1/billing/status \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/billing/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/billing/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/billing/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/billing/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "billing_status": "trialing",
  "plan_tier": "<string>",
  "trial_ends_at": "2023-11-07T05:31:56Z",
  "trial_days_left": 123,
  "trial_expired": true
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Parameters

Example Request

Response

Fields

Errors

Authorizations

Response

​Parameters

​Example Request

​Response

​Fields

​Errors

Authorizations

Response

Parameters

Example Request

Response

Fields

Errors