# Billing & usage

Billing is organization-scoped: one plan, one wallet, and one invoice stream are shared across all of an organization's workspaces. This page covers the parts of billing a developer actually touches: how usage is metered, how to read it, and how your plan tier shapes the operational limits your integration runs against. For account operations — pricing details, payment methods, tax — see the Knowledge base ([Plans & pricing](/docs/knowledge-base/billing/plans-and-pricing), [Usage & invoices](/docs/knowledge-base/billing/usage-and-invoices)).

All billing endpoints live under `/v1/organization/billing/...`, are gated by the `org:billing` scope, and are session-authenticated — billing is managed by people (owners and billing admins, see [Users, teams & roles](/docs/guides/users-teams-roles)), not by API keys.

## Plans and tiers

Your organization subscribes to one plan. The plan catalog is available at `GET /v1/billing/plans`; your current subscription lives at `GET /v1/organization/billing/plan`, and plan changes go through `POST /v1/organization/billing/plan/change`. Each plan carries a **tier** — free, startup, growth, or custom — and the tier is what your integration feels operationally:

- **Included sending volume.** Each plan includes a monthly allotment of email sends; sends beyond it are metered as overage.
- **Rate-limit ceilings scale with tier.** Rate limits resolve as the maximum of a base value, your tier's value, and any per-organization override. The `email_send` group is the clearest example: 10 requests/min at base (free), 100/min on startup, 1,000/min on growth, with custom-tier ceilings set by arrangement. Higher tiers raise the list/read ceilings too. The model and headers are described in [Rate limits](/docs/guides/rate-limits); per-channel numbers live on the channel pages.
- **Resource limits.** Caps such as how many workspaces, sending domains, IP pools, and dedicated IPs your organization can hold are set per plan and adjustable per organization — if you hit one, contact support rather than working around it.

If you are approaching a ceiling, that is a conversation, not a wall: per-organization overrides above the tier values are a normal part of scaling on Bird.

## Usage metering

Every send is metered against your organization's current billing period. `GET /v1/organization/billing/usage` returns the live picture — per product, for the current period:

```bash
curl https://us1.platform.bird.com/v1/organization/billing/usage \
  -H "Authorization: Bearer <your-credential>" \
  -H "X-Organization-Id: <organization-id>"
```

```json
{
  "period": { "start": "2026-06-01T00:00:00Z", "end": "2026-06-30T23:59:59Z" },
  "items": [
    {
      "product": { "slug": "email_transactional", "name": "Email sends" },
      "pricing_model": "metered",
      "metered": { "quantity": 1284300, "included": 2000000, "overage": 0, "utilization_pct": 64.2 }
    }
  ]
}
```

Each item is one of two pricing models, named by the `pricing_model` discriminator:

- **`metered`** — products with an included allotment on your plan (email sends). The `metered` object gives `quantity` used, `included` on the plan, `overage` beyond it, and `utilization_pct`. One accepted message is one metered unit.
- **`rate_card`** — pay-as-you-go products billed per use against a rate card. The `transactional` object gives a `transaction_count` and the `net_amount` spent so far this period.

By default the response covers every product you are subscribed to plus any pay-as-you-go product you have used this period; pass `products[]` to filter. The same data backs the [**Billing and payments → Usage**](https://bird.com/dashboard/o/billing/usage) page in the dashboard.

## The wallet

Each organization has a wallet — a shared prepaid balance that all workspaces draw from. Top-ups and plan charges both flow through it: `POST /v1/organization/billing/wallets/{wallet_id}/topup` initiates a top-up payment, and `GET /v1/organization/billing/wallets/{wallet_id}/transactions` is the full ledger of credits and charges, so you can reconcile every movement programmatically.

To avoid surprises, set billing notification addresses: the `notification_emails.billing` list (managed via `PATCH /v1/organization`, or in the dashboard under [**Billing and payments**](https://bird.com/dashboard/o/billing/settings)) receives low-balance warnings, invoice notifications, and plan-change confirmations. Point it at a team alias, not an individual — billing alerts that land in one person's inbox are billing alerts that get missed.

## Invoices

Invoices are issued per organization and available at `GET /v1/organization/billing/invoices`, with individual invoices (including line items) at `GET /v1/organization/billing/invoices/{invoice_id}`. Invoices reflect the same metering shown by the usage endpoint: your plan's recurring charge plus any metered overage and pay-as-you-go spend for the period. For how invoices are structured, payment timing, and dunning, see [Usage & invoices](/docs/knowledge-base/billing/usage-and-invoices) in the Knowledge base.

## Next steps

- [Rate limits](/docs/guides/rate-limits) — the base/tier/override model your tier feeds into
- [Plans & pricing](/docs/knowledge-base/billing/plans-and-pricing) — what each plan includes
- [Usage & invoices](/docs/knowledge-base/billing/usage-and-invoices) — reading invoices, payment methods, and billing operations
- [Users, teams & roles](/docs/guides/users-teams-roles) — who can manage billing (`org:billing`)