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 in this guide 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 enterprise), 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, making the full new allowance available for the rest of the current period. Downgrades and cancellations take effect at the end of the current billing period. See Plan changes & renewals for the failed-payment sequence and other timing rules. Design integrations to handle errors when an account exceeds its allowance.

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:

Exemplo de código

{
  "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). A message can draw on the wallet twice: Bird's own fee when the send is processed, and a third-party fee (a carrier surcharge on SMS, Meta's share on WhatsApp) when the message is delivered. On WhatsApp the message's cost breaks the two out; on SMS the carrier fee is charged without being reported on the message yet. 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. SMS is refused at the API with a 402; a WhatsApp send is accepted and then rejected once Bird tries to charge it. A delivery-time fee the balance cannot cover is skipped rather than rejected, so the message still reaches its recipient. For transactional volume, configure auto top-up and a low-balance alert on the Billing overview, or monitor and alert on your side. Payment methods and wallet covers both dashboard controls. 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, and fall back to the organization owner otherwise. Set that list under Settings > Organization, or with PATCH /v1/organization. Use a monitored team alias for that list so billing mail does not depend on one person's inbox.

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)