# Billing

The plans, the team's plan and what it includes, and its invoices.

Source: https://docs.orbits.africa/api/billing

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](https://docs.orbits.africa/billing/plans).

Endpoints:

- `GET /v1/plans`: The plans and their prices
- `GET /v1/teams/{team}/billing`: The team's plan and billing state
- `GET /v1/teams/{team}/billing/invoices`: The team's invoices
- `GET /v1/teams/{team}/billing/invoices/{invoice}`: One invoice, as a receipt

## The billing object



- `plan` (string, required): One of `free`, `pro`.
- `status` (string, required): `past_due`: Pro, but the period has ended unpaid and the team is in its grace period. One of `free`, `active`, `past_due`.
- `source` (string or null, required): `comp`: Pro granted by Orbits, nothing to pay. Null on Free. One of `flutterwave`, `comp`.
- `enforced` (boolean, required): Whether plan limits are switched on. When false every feature works for every team.
- `current_period` (null or object, required)
  - `start` (string, required)
  - `end` (string or null, required): Null for a plan with no end (`comp`).
- `cancel_at_period_end` (boolean, required)
- `grace_ends_at` (string or null, required)
- `price` (object, required): Pro's price today, for the upgrade button.
  - `usd_cents` (integer, required)
  - `ngn` (integer or null, required)
  - `rate` (string or null, required)
- `next_charge` (null or object, required)
  - `usd_cents` (integer, required)
  - `ngn` (integer or null, required)
- `entitlements` (object, required): What this team may do now. All true (and `sleeps_when_idle` false) while `enforced` is false.
  - `functions` (boolean, required)
  - `sandboxes` (boolean, required)
  - `analytics` (boolean, required)
  - `speed_insights` (boolean, required)
  - `sleeps_when_idle` (boolean, required)
- `card` (null or object, required)
  - `brand` (string or null, required)
  - `last4` (string, required)
  - `exp` (string or null, required)
- `can_manage` (boolean, required): True for owners, who may change billing.
- `banner` (null or BillingAlert, required): The owners' notice about the plan, or null. Always null for members.
  - `kind` (string, required): Always `downgraded`.
  - `at` (string)
  - `amount_ngn` (integer or null)
  - `charge` (string): One of `automatic`, `manual`.
  - `grace_ends_at` (string)
  - `ends_at` (string)
## The invoice object



- `id` (string, required)
- `kind` (string, required): A first purchase, an automatic renewal, or a payment made by hand while already Pro or past due. One of `initial`, `renewal`, `manual`.
- `status` (string, required): One of `open`, `paid`, `failed`, `void`.
- `usd_cents` (integer, required): The dollar price.
- `ngn_amount` (integer, required): Whole Naira charged: the dollar price at `fx_rate`, rounded up to a whole ₦100, locked when the invoice was made.
- `fx_rate` (string, required): The USD → NGN rate it was converted at.
- `period` (object or null, required): The month it paid for; null until it is paid.
  - `start` (string, required)
  - `end` (string, required)
- `reference` (string, required)
- `method` (string or null, required): How it was paid; null until it is. One of `card`, `bank_transfer`, `other`.
- `paid_at` (string or null, required)
- `created_at` (string, required)
## The plans and their prices

```http
GET /v1/plans
```

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).

Token: any API token (`read` or `full`).

Example:

```sh
curl "https://api.theorbits.app/v1/plans" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "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"
}
```

Errors:

## The team's plan and billing state

```http
GET /v1/teams/{team}/billing
```

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.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/billing" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "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"
  }
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## The team's invoices

```http
GET /v1/teams/{team}/billing/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.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `limit` (integer): From 1 to 100. Defaults to `25`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "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"
    }
  ]
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## One invoice, as a receipt

```http
GET /v1/teams/{team}/billing/invoices/{invoice}
```

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.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `invoice`: An `id` from `GET .../billing/invoices`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices/inv_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "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
  }
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
