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 how billing shapes an integration: how usage is metered, how to read the current picture, and how your plan tier sets the operational limits your integration runs against. For account operations (pricing details, payment methods, tax), see the Knowledge base: Plans & pricing and Usage, spend & invoices.

Billing endpoints live under /v1/organization/billing/... and are gated by the org:billing scope (the plan catalog at GET /v1/billing/plans is the exception; it needs no authentication). org:billing is an organization-role scope that can't be granted to a workspace API key, so no bk_* key can call these endpoints. Billing is managed by people (owners and billing admins; see Users, teams & roles), and the endpoint names below explain what the dashboard does rather than describe an API-key integration. The same data backs the Billing and payments section of the dashboard, whose pages (Overview, Usage, Invoices, Spend, Settings) are covered in the Knowledge base articles linked throughout.

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 allowance of email sends, metered per recipient: a message to three recipients consumes three. On paid plans, sends beyond the allowance are metered as overage up to a hard ceiling; past the ceiling, sends are rejected with a limit error until the period resets. The Free plan has no overage at all: it stops at its monthly and daily caps. Allowances, caps, and the overage ceiling are in Plans & pricing.
Rate-limit ceilings scale with plan. Rate limits start from a base value, your plan replaces it with a higher one, and a per-organization override replaces both, so higher plans raise the send and read ceilings. The model, every group's base rate, and the headers are described in Rate limits.
Resource limits. Caps such as how many 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.

Upgrades apply immediately (the full new allowance is available for the rest of the current period); downgrades and cancellations take effect at the end of the current billing period. The timing rules, including the failed-payment sequence during which overage is suspended and over-allowance sends return errors, are in Plan changes & renewals; if your integration should degrade gracefully at the allowance boundary, that page is worth a read.

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, and it's what the dashboard's Usage page renders. Filtered to one product with products[]=email_transactional, a response looks like this:

Codebeispiel

{
  "items": [
    {
      "data_complete": true,
      "metered": {
        "included": 1000,
        "overage": 0,
        "quantity": 6,
        "utilization_pct": 0.6
      },
      "period_end": "2026-08-23T00:00:00Z",
      "period_start": "2026-07-23T00:00:00Z",
      "pricing_model": "metered",
      "product": {
        "id": "prd_5zcwpah645866axcpx4v0as87z",
        "name": "Email Transactional",
        "pricing_model": "metered",
        "slug": "email_transactional",
        "unit_name": "email"
      },
      "subscription_id": null
    }
  ],
  "period_end": "2026-08-01T00:00:00Z",
  "period_start": "2026-07-01T00:00:00Z"
}

The response carries a top-level period_start / period_end (the calendar month), and each item carries its own measurement window: the plan period for the metered email product, the calendar month for pay-as-you-go products. Each item names its product and one of two pricing models, using the pricing_model discriminator:

metered: products with an included allowance on your plan (email sends). The metered object gives the quantity used, the included allowance, overage beyond it, and utilization_pct.
rate_card: pay-as-you-go products billed per use against a rate card (SMS, WhatsApp). Each unit is charged from the wallet at send time; the transactional object gives the transaction_count, the net_amount spent so far, and a projection for the full period.

By default the response covers every product with a subscription or usage in the current period; pass products[] to filter, or breakdown[] for the per-day, per-country, and per-sending-domain splits the Usage page charts.

The Usage page in the Bird dashboard: total spend with projection, per-channel send counts, and daily usage charts

The wallet

Each organization has a wallet: a shared prepaid balance that every charge flows through. Plan renewals, overage, and pay-as-you-go sends all debit the wallet; a saved card exists to fill it (top-ups, auto top-up, and covering a renewal the balance can't). 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, the same ledger the dashboard's Spend page renders, so every wallet movement is accounted for in one place. Each top-up payment that settles also produces a durable receipt: list them at GET /v1/organization/billing/payment-receipts, and download one as a PDF named receipt-<id>.pdf from GET /v1/organization/billing/payment-receipts/{receipt_id}/pdf.

Operationally, the wallet is a dependency of pay-as-you-go sending: SMS and WhatsApp sends are rejected when the balance can't cover them. If you send transactionally at volume, configure auto top-up and the low-balance alert threshold from the wallet panel on the Billing overview (Payment methods & wallet walks through both), or monitor the balance and alert on your side. Low-balance warnings and payment-failure notices go to the organization owners; invoice emails go to the notification_emails.billing list when one is set (managed under Settings → Organization, or via PATCH /v1/organization), falling back to the organization owner otherwise. Point that list at a team alias, not an individual: billing mail that lands in one person's inbox is billing mail that gets missed.

Invoices

Invoices are issued per organization, one per calendar month, and available at GET /v1/organization/billing/invoices, with individual invoices (including line items) at GET /v1/organization/billing/invoices/{invoice_id} and a PDF rendering at GET /v1/organization/billing/invoices/{invoice_id}/pdf. 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, statuses, and payment timing, see Usage, spend & invoices in the Knowledge base.

Next steps

Rate limits: the base/tier/override model your tier feeds into
Plans & pricing: what each plan includes, overage, and pay-as-you-go pricing
Plan changes & renewals: upgrade/cancel timing and the failed-payment sequence
Users, teams & roles: who can manage billing (org:billing)