Documentation
Sign inGet started
Jetzt starten
Anleitungen
API-Referenz
SDKs & CLI
Wissensdatenbank
Changelog

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, Usage & 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), 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; 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:
Codebeispiel
curl https://us1.platform.bird.com/v1/organization/billing/usage \
  -H "Authorization: Bearer <your-credential>" \
  -H "X-Organization-Id: <organization-id>"
Codebeispiel
{
  "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 usage page in the dashboard under Billing and payments → Usage.

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) 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 in the Knowledge base.

Related