Billing

How it works

• Every organization has exactly one credit_balance, denominated in BRL.
• Top ups are one-off Stripe Payment Intents. We complete the top up in-transaction when Stripe's webhook arrives.
• Each billable event (message.delivered, first-time phone_number.verified, tts.characters, llm.tokens.used, and successful production transcription) writes a UsageRecord priced against the active rate card — and, for the per-message transport fee, discounted by your plan.
• Sandbox is free to your wallet, but sandbox message records still mirror active rate-card pricing so you can test reconciliation before production — they never debit the balance or consume package quota. Non-message meters are written at cost_brl = 0 outside production.

Top up

Top-ups are created from the dashboard, where the signed-in user can use Stripe Elements or PIX without exposing dashboard session endpoints as public integration APIs. The balance is credited atomically when Stripe's webhook marks the intent as succeeded.

Balance and ledger

The ledger is a cursor-paginated stream of credits (top ups) and debits (usage records). Each entry carries the trace_id that produced it so you can reconcile a charge back to the exact message. Debit entries include uncollected_brl when delivered usage could not be fully collected without crossing the -R$5 production credit floor.

Rate card

Rate cards are effective-dated. The active card is the one whose window covers now, and it is the authoritative source for the meter rates below — the transport fee and the Meta reference rates. Plan fees, multipliers, throughput, and phone allowances are not on the rate card; those live on the plan catalog further down. Each entry carries a kind so you can tell what Tyxter actually debits (billed) from what is reproduced for reference only (meta_reference).

What Tyxter charges

Tyxter bills one flat transport fee per outbound WhatsApp message — msg.transport, R$0.05 per message — whatever the conversation category. A subscription plan discounts that fee by a multiplier. It is a discount on the per-message rate, not a bundled quota: you still pay for every message, just less per message.

msg.transport   R$0.05 / message      base rate
                x 1.00  = R$0.05      Free (no subscription)
                x 0.60  = R$0.03      Standard
                x 0.32  = R$0.016     Growth

The other meters Tyxter bills to your credit balance:

phone.number.month       R$50.00 / number / month (numbers Tyxter provisions for you)
msg.instagram.outbound   R$0.05 / message
tts.characters           R$0.0001 / character rendered
llm.tokens.used          R$0.015 / 1k tokens (input + output)
template.generation      R$0.05 / generation (production only)

Production inbound-audio transcription uses stt.audio.secondwhen Tyxter’s platform credential runs the provider and stt.audio.second.byok when your connected OpenAI STT credential does. Set up OpenAI STT BYOK in the media guide. The chosen source and meter stay fixed for that run, including automatic retries. A new manual retry may select the configuration available at that time. Disconnecting your OpenAI STT credential withdraws the override, so every transcription that was not already attributed to it — including one still queued — meters at stt.audio.secondon Tyxter’s platform credential again. Starting 24 August 2026 at 00:01 America/Sao_Paulo (03:01 UTC), the platform rate is R$0.0043 per audio second and the BYOK rate is R$0.0005 per audio second. A 60-second successful transcript is R$0.2580 with Tyxter’s credential or R$0.0300 with BYOK. Pricing uses the rate card effective at the usage event, so earlier usage keeps its earlier price. Consult GET /v1/rate-cards/current for the currently effective card. If the selected meter has no active entry, Tyxter fails the transcript before reading audio or calling the provider and records transcription_billing_rate_unavailable. It does not silently switch to the platform credential or create zero-priced production usage.

Meta reference rates

Meta bills your outbound WhatsApp messages directly to your own Meta account, per delivered message, at a rate that depends on which of its categories the message falls into. Tyxter is not the billing party for them, never debits them from your credit balance, and never marks them up. They appear on the rate card as kind: "meta_reference".

When available, the estimate is calculated from the immutable rate selected at each usage event's timestamp. It stays separate from cost_brl, your credit balance, ledger, invoice, package quota, and the always-zero pre-BSP meta_pass_through_fee_brl. Meta's own account and invoice remain authoritative.

Sandbox usage reports the same estimate fields so you can model production Meta costs before going live. Sandbox messages are simulated inside Tyxter — Meta never delivers or bills them, so a sandbox estimate is a modeling aid, not an incoming charge.

Why Meta invoices you and not Tyxter — and who owns the WhatsApp Business Account that invoice belongs to — is set out on the Tyxter and Meta page.

Plans

A plan is a monthly subscription that lowers the per-message transport fee and raises your throughput and phone-number limits. Free is the absence of a subscription rather than something you buy — you get the base rate and the smallest limits, with no monthly fee.

Plans, like the credit balance, attach to the organization: one subscription covers every project and environment under it, and the discounted per-message rate applies to traffic from all of them. There is no per-project plan or wallet. Per-project attribution survives the shared wallet — invoices are generated per project and a monthly spend limit can be set per project in the dashboard. Integrations that run one project per end customer are covered on the Multi-tenant platforms page.

GET /v1/billing/plans is the live catalog and the source of truth for the money columns. Every offering carries monthly_fee_brl, annual_pix_fee_brl, platform_fee_multiplier, max_phones, and the already-multiplied net_transport_rate_brl — read that last field and you have the exact per-message rate the plan bills, with no arithmetic. It lists what you can buy, so Free is not in it. To read the plan your organization is on right now, Free included, call GET /v1/billing/plan, where status: "none"means Free. Paying a year up front by PIX is also offered, at each plan’s annual_pix_fee_brl.

Sustained throughput is the ceiling your plan sets on outbound sends, with a bucket of exactly twice that many messages available for a burst. It is a ceiling, not a guarantee: each number sends at whichever is lower, your plan’s rate or that number’s own Meta messaging limit — so a number Meta still rates at 30 msg/s sends at 30 msg/s on every plan. The dashboard shows the effective limit per number.

The phone-number allowance counts active production numbers of both kinds — provisioned by Tyxter and brought from your own Meta account — across every project in the organization, whichever WABA each number belongs to. Going past it returns 402 plan_phone_limit_reached on the next provision or connect; numbers you already have are never removed when you move to a smaller plan.

Numbers Tyxter provisions for you have their own limit, separate from that allowance: 1 on Free, 3 on Standard and 10 on Growth by default. On Growth that reads as up to 10 Tyxter-provisioned numbers by default (R$50/number/month) — more on request · unlimited bring-your-own numbers, because Growth sets no plan allowance at all; on Free and Standard the allowance above still counts your own numbers too. The ceiling counts only active production numbers Tyxter provisioned: a number you brought from your own Meta account never counts toward it, and sandbox provisioning is never capped. A provision request past the ceiling returns 409 phone_number_limit_reached — release a Tyxter-provisioned number to free its slot, or contact us and we will raise the limit for your organization. The plan allowance is evaluated first, so an organization already at its allowance sees 402 plan_phone_limit_reached and should upgrade rather than ask for a higher ceiling. The ceiling is not published on GET /v1/billing/plans; max_phones there is the plan allowance, which counts numbers of both kinds.

Subscribing, switching, and cancelling are documented on the Billing API reference.

Spend limit

Set a monthly BRL cap per project from the dashboard. Once month-to-date production spend reaches the cap, POST /v1/messages returns 402 spend_limit_exceeded until the next calendar month rolls over — or you raise the cap. A spend_limit.hit webhook fires on the crossing.

Low-balance alerts

When the balance crosses the configured threshold downward (default R$10), a credit.low_balance webhook fires exactly once per decrement that caused the crossing. Subscribe to it to auto-top-up.

Invoices

Monthly CSV roll-up per project. BuildInvoiceUseCase is idempotent on (project_id, period_start); the download URL is a 15-minute presigned S3 GET.