API reference · TeamBilling
Billing
The plans, the team's plan and what it includes, and its invoices.
Read which plan a team is on, what it includes, and its invoices. Paying, cancelling and resuming happen in the dashboard, by an owner: an API token may read billing but never change it. See Plans.
The billing object
Fields
planstringrequiredOne of
free,pro.statusstringrequiredpast_due: Pro, but the period has ended unpaid and the team is in its grace period.One of
free,active,past_due.sourcestring or nullrequiredcomp: Pro granted by Orbits, nothing to pay. Null on Free.One of
flutterwave,comp.enforcedbooleanrequiredWhether plan limits are switched on. When false every feature works for every team.
current_periodnull or objectrequiredShow 2 child fieldsHide child fields
startstringrequiredendstring or nullrequiredNull for a plan with no end (
comp).
cancel_at_period_endbooleanrequiredgrace_ends_atstring or nullrequiredpriceobjectrequiredPro's price today, for the upgrade button.
Show 3 child fieldsHide child fields
usd_centsintegerrequiredngninteger or nullrequiredratestring or nullrequired
next_chargenull or objectrequiredShow 2 child fieldsHide child fields
usd_centsintegerrequiredngninteger or nullrequired
entitlementsobjectrequiredWhat this team may do now. All true (and
sleeps_when_idlefalse) whileenforcedis false.Show 5 child fieldsHide child fields
functionsbooleanrequiredsandboxesbooleanrequiredanalyticsbooleanrequiredspeed_insightsbooleanrequiredsleeps_when_idlebooleanrequired
cardnull or objectrequiredShow 3 child fieldsHide child fields
brandstring or nullrequiredlast4stringrequiredexpstring or nullrequired
can_managebooleanrequiredTrue for owners, who may change billing.
bannernull or BillingAlertrequiredThe owners' notice about the plan, or null. Always null for members.
Show 6 child fieldsHide child fields
kindstringrequiredAlways
downgraded.atstringamount_ngninteger or nullchargestringOne of
automatic,manual.grace_ends_atstringends_atstring
The invoice object
Fields
idstringrequiredkindstringrequiredA first purchase, an automatic renewal, or a payment made by hand while already Pro or past due.
One of
initial,renewal,manual.statusstringrequiredOne of
open,paid,failed,void.usd_centsintegerrequiredThe dollar price.
ngn_amountintegerrequiredWhole Naira charged: the dollar price at
fx_rate, rounded up to a whole ₦100, locked when the invoice was made.fx_ratestringrequiredThe USD → NGN rate it was converted at.
periodobject or nullrequiredThe month it paid for; null until it is paid.
Show 2 child fieldsHide child fields
startstringrequiredendstringrequired
referencestringrequiredmethodstring or nullrequiredHow it was paid; null until it is.
One of
card,bank_transfer,other.paid_atstring or nullrequiredcreated_atstringrequired
The plans and their prices
Orbits has two plans. Free is unlimited projects, with apps that scale to zero, and without server functions, sandboxes and Analytics or Speed Insights. Pro is usd_cents: 500 a month and has all of them. ngn is the Naira amount charged for the price: the USD price at rate (a rate Orbits sets, USD → NGN), rounded up to a whole ₦100. It is null until the server has a rate set (then Pro can't be bought yet). The amount a payment is actually taken for is locked on the invoice when checkout starts, so show ngn as "about" only if you need to hedge; POST .../billing/checkout refuses with 409 if the amount you showed no longer matches.
features describe the plan, not the team, and are the same whether or not limits are being enforced yet (enforced on GET /v1/teams/{team}/billing says whether they are).
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Response 200
The plans.itemsarray of PlanrequiredShow 5 child fieldsHide child fields
idstringrequiredOne of
free,pro.namestringrequiredusd_centsintegerrequiredngninteger or nullrequiredWhole Naira at the current rate, rounded up to a whole ₦100; 0 for Free; null while no rate is set.
featuresPlanFeaturesrequiredShow 6 child fieldsHide child fields
unlimited_projectsbooleanrequiredfunctionsbooleanrequiredThe
functionworkload type. On Free the same frameworks (Next.js, SvelteKit, Nuxt, Remix...) run as ordinary apps.sandboxesbooleanrequiredanalyticsbooleanrequiredspeed_insightsbooleanrequiredsleeps_when_idlebooleanrequiredApps scale to zero when idle (Free). Not running yet: Free apps stay on until that ships.
ratestring or nullrequiredThe USD → NGN rate in use, as a decimal string, or null when none is set.
curl "https://api.theorbits.app/v1/plans" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"items": [
{
"id": "free",
"name": "Pro",
"usd_cents": 500,
"ngn": 8000,
"features": {
"unlimited_projects": false,
"functions": false,
"sandboxes": false,
"analytics": false,
"speed_insights": false,
"sleeps_when_idle": false
}
}
],
"rate": "1600"
}The team's plan and billing state
What the Settings Plan card and the Billing page show: the plan, whether it is active, past_due (a payment failed and the team is in its grace period) or free, the current period, what the next charge will be, what the plan allows, and (for owners) the card on file. enforced is false while Orbits has not switched plan limits on: every feature works for every team and entitlements all say true, although plan still says what the team is on.
Permissions: Any team member sees the plan; the card is shown to owners only. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Response 200
The billing state.planstringrequiredOne of
free,pro.statusstringrequiredpast_due: Pro, but the period has ended unpaid and the team is in its grace period.One of
free,active,past_due.sourcestring or nullrequiredcomp: Pro granted by Orbits, nothing to pay. Null on Free.One of
flutterwave,comp.enforcedbooleanrequiredWhether plan limits are switched on. When false every feature works for every team.
current_periodnull or objectrequiredShow 2 child fieldsHide child fields
startstringrequiredendstring or nullrequiredNull for a plan with no end (
comp).
cancel_at_period_endbooleanrequiredgrace_ends_atstring or nullrequiredpriceobjectrequiredPro's price today, for the upgrade button.
Show 3 child fieldsHide child fields
usd_centsintegerrequiredngninteger or nullrequiredratestring or nullrequired
next_chargenull or objectrequiredShow 2 child fieldsHide child fields
usd_centsintegerrequiredngninteger or nullrequired
entitlementsobjectrequiredWhat this team may do now. All true (and
sleeps_when_idlefalse) whileenforcedis false.Show 5 child fieldsHide child fields
functionsbooleanrequiredsandboxesbooleanrequiredanalyticsbooleanrequiredspeed_insightsbooleanrequiredsleeps_when_idlebooleanrequired
cardnull or objectrequiredShow 3 child fieldsHide child fields
brandstring or nullrequiredlast4stringrequiredexpstring or nullrequired
can_managebooleanrequiredTrue for owners, who may change billing.
bannernull or BillingAlertrequiredThe owners' notice about the plan, or null. Always null for members.
Show 6 child fieldsHide child fields
kindstringrequiredAlways
downgraded.atstringamount_ngninteger or nullchargestringOne of
automatic,manual.grace_ends_atstringends_atstring
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/billing" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"plan": "free",
"status": "free",
"source": "flutterwave",
"enforced": false,
"current_period": {
"start": "2026-11-10T09:30:00Z",
"end": "2026-11-10T09:30:00Z"
},
"cancel_at_period_end": false,
"grace_ends_at": "2026-11-10T09:30:00Z",
"price": {
"usd_cents": 1,
"ngn": null,
"rate": null
},
"next_charge": {
"usd_cents": 1,
"ngn": null
},
"entitlements": {
"functions": false,
"sandboxes": false,
"analytics": false,
"speed_insights": false,
"sleeps_when_idle": false
},
"card": {
"brand": null,
"last4": "4471",
"exp": "09/28"
},
"can_manage": false,
"banner": {
"kind": "upcoming",
"at": "2026-11-10T09:30:00Z",
"amount_ngn": null,
"charge": "automatic"
}
}The team's invoices
The Invoices list: payments made for Pro, newest first. Payments that were started and never paid are not listed. limit is 1 to 100 (default 25); there is no cursor yet.
Permissions: Team owners only; other members get 403.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.
Query parameters
limitintegerFrom 1 to 100. Defaults to
25.
Response 200
The invoices.itemsarray of InvoicerequiredShow 11 child fieldsHide child fields
idstringrequiredkindstringrequiredA first purchase, an automatic renewal, or a payment made by hand while already Pro or past due.
One of
initial,renewal,manual.statusstringrequiredOne of
open,paid,failed,void.usd_centsintegerrequiredThe dollar price.
ngn_amountintegerrequiredWhole Naira charged: the dollar price at
fx_rate, rounded up to a whole ₦100, locked when the invoice was made.fx_ratestringrequiredThe USD → NGN rate it was converted at.
periodobject or nullrequiredThe month it paid for; null until it is paid.
Show 2 child fieldsHide child fields
startstringrequiredendstringrequired
referencestringrequiredmethodstring or nullrequiredHow it was paid; null until it is.
One of
card,bank_transfer,other.paid_atstring or nullrequiredcreated_atstringrequired
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"items": [
{
"id": "id",
"kind": "initial",
"status": "open",
"usd_cents": 1,
"ngn_amount": 1,
"fx_rate": "fx-rate",
"period": {
"start": "2026-11-10T09:30:00Z",
"end": "2026-11-10T09:30:00Z"
},
"reference": "reference",
"method": "card",
"paid_at": "2026-11-10T09:30:00Z",
"created_at": "2026-11-10T09:30:00Z"
}
]
}One invoice, as a receipt
The invoice with who paid, for which team, what for, and the card (brand and last four) it was paid with. There is no PDF; the dashboard renders the receipt.
Permissions: Team owners only. An invoice of another team is 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.invoicestringrequiredAn
idfromGET .../billing/invoices.
Response 200
The receipt.idstringrequiredkindstringrequiredA first purchase, an automatic renewal, or a payment made by hand while already Pro or past due.
One of
initial,renewal,manual.statusstringrequiredOne of
open,paid,failed,void.usd_centsintegerrequiredThe dollar price.
ngn_amountintegerrequiredWhole Naira charged: the dollar price at
fx_rate, rounded up to a whole ₦100, locked when the invoice was made.fx_ratestringrequiredThe USD → NGN rate it was converted at.
periodobject or nullrequiredThe month it paid for; null until it is paid.
Show 2 child fieldsHide child fields
startstringrequiredendstringrequired
referencestringrequiredmethodstring or nullrequiredHow it was paid; null until it is.
One of
card,bank_transfer,other.paid_atstring or nullrequiredcreated_atstringrequiredteamobjectrequiredShow 3 child fieldsHide child fields
idstringrequiredslugstringrequirednamestringrequired
payer_emailstring or nullrequireddescriptionstringrequiredcardobject or nullrequiredThe card it was paid with; null when it is unpaid or was paid by bank transfer.
Show 3 child fieldsHide child fields
brandstring or nulllast4stringrequiredexpstring or null
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices/inv_01jc8x6e4mq2v7r9y3t5b0zp8w" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"id": "id",
"kind": "initial",
"status": "open",
"usd_cents": 1,
"ngn_amount": 1,
"fx_rate": "fx-rate",
"period": {
"start": "2026-11-10T09:30:00Z",
"end": "2026-11-10T09:30:00Z"
},
"reference": "reference",
"method": "card",
"paid_at": "2026-11-10T09:30:00Z",
"created_at": "2026-11-10T09:30:00Z",
"team": {
"id": "id",
"slug": "my-app",
"name": "my-app"
},
"payer_email": "ada@example.com",
"description": "Orbits Pro",
"card": {
"brand": null,
"last4": "last4",
"exp": null
}
}