---
title: "Get plan and usage"
method: GET
path: "/billing"
tags: ["Billing"]
---

# Get plan and usage

`GET /billing`

## Request

- Base URL: `https://api.rizamo.com/v1`
- URL: `https://api.rizamo.com/v1/billing`
- Auth: HTTP bearer

Billed per connected account, the first 2 free. Only keys and people that reach every profile see it, since the plan counts every profile's accounts.

## Response `200`

OK

- Billing
  - `status` 'free' | 'active' | 'past_due' | 'unpaid' | 'cancelling', required: free: up to 2 accounts, no card. active: a paid plan. past_due: a payment failed and Stripe retries it for up to 14 days; everything works. unpaid: still unpaid after 14 days, so accounts beyond 2 are paused until it is paid. cancelling: the plan ends at `periodEnd`, then the team is on the free plan.
  - `interval` 'month' | 'year', nullable, required: Monthly or yearly; null on the free plan.
  - `accounts` object, required
    - `connected` integer, required: Every account the team has, in any billing state.
    - `active` integer, required
    - `awaitingPayment` integer, required
    - `paused` integer, required
    - `billed` integer, required: What the plan bills this period: the larger of the accounts connected now and those already paid this period. Removed accounts drop off at renewal. Without a paid plan, the active accounts the free plan covers.
    - `free` integer, required: Accounts that never cost anything.
  - `price` object, required
    - `perPeriod` number, required: What the billed accounts cost per period (month or year), in US dollars, before any discount and tax.
    - `nextAccount` number, required: What one more account adds per period, before any discount and tax.
    - `discountPercent` number, nullable, required: A discount the plan keeps, such as the FOUNDING code's 50%.
    - `currency` 'usd', required
  - `periodEnd` string, date-time, nullable, required: When the period ends: the next renewal, or the end of a plan that is cancelling.
  - `apiCap` object, required: What an owner lets connect links add on a paid plan (ADR 0025).
    - `accounts` integer, nullable, required: The most accounts connect links (the API and MCP) may add to a paid plan each period. Null, the default, is no limit: none is set until a team owner sets one in the web app.
    - `added` integer, required: Accounts connect links added and charged this period. Beyond the cap, more arrive awaiting_payment until an owner pays.
  - `action` 'checkout' | 'pay' | 'update_card' | 'choose_accounts', nullable, required: What a team owner must do in the web app, if anything. checkout: accounts wait for a paid plan to start, or more accounts are active than the free plan keeps (connected before billing was on), and the newest pause at the daily check (04:00 UTC) unless a plan starts. pay: an added account's charge needs the card holder (3-D Secure) or failed. update_card: a renewal failed. choose_accounts: the plan ended or went unpaid, and the owner may pick which 2 accounts stay active.

## Other responses

- `401`: `unauthorized`: No API key or sign-in, or the key does not work: it was deleted, or it expired.
- `403`: `forbidden`: The caller may not do this: the key or agent lacks the scope (the message names it), or the action needs another role or a fresh sign-in.
- `429`: `rate_limited`: Over one of Rizamo's limits, or a network asked Rizamo to slow down: wait for `Retry-After` seconds, or as long as the message says.
- `500`: `internal`: Our side failed: retry, and send the `requestId` if it keeps failing.
- `503`: `timeout`: The request took too long to work out, most often a report: try again in a moment, or ask a report for a shorter period or one profile.

---

[API](https://skmtc.dev/rizamo/apis/rizamo-api.md) - [All operations](https://skmtc.dev/rizamo/apis/rizamo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rizamo/apis/rizamo-api/revisions/31b0c1b1ffb5?raw)
