Billing

Balance

The required production_blocked field reports the current production API-key and MCP credit restriction, including the existing recovery exemptions, even when this read uses a sandbox key. It is not a general send-eligibility verdict. Activation keeps an engaged block through partial top-ups and zero until the wallet becomes positive; a positive wallet may still be insufficient for the next rental fee.

held_brl is the credit set aside by outstanding production holds, such as a payment completion fee waiting for the payment outcome. A hold is already deducted from balance_brl, so balance_brl + held_brl is the balance with nothing held. A hold is not spend: it is either charged as a usage debit or released back to the wallet. Sandbox holds never move the wallet and are not counted.

Response

Rate-card history

Returns effective-dated BRL rate cards in reverse chronological order. Use the cursor fields to page through historical pricing.

Query

Response

Current rate card

Response

Available plans

Lists the purchasable plan catalog, including each plan's effective transport rate, throughput tier, and phone-number allowance.

Response

Current plan

Returns the organization's effective subscription. A status of none represents the free tier.

Response

Subscribe to a plan

Requires billing:write and supports Idempotency-Key. Card subscriptions charge the saved default card; annual Pix subscriptions return checkout details in pix.

Request body

Response

Change the current plan

Changes an active subscription to another catalog offering. Reuse one Idempotency-Key across retries. The switch is asynchronous: the response still shows the current plan, and the new plan's entitlement applies when the payment provider confirms the paid invoice — poll GET /v1/billing/plan to observe it.

Request body

Response

Cancel the current plan

Schedules cancellation according to the current billing period. The request has no JSON body and supports Idempotency-Key.

Response

Packages

Lists past package purchases and the package offerings currently available to the organization.

Query

Response

Purchases a package with a saved card. This write requires billing:write and supports Idempotency-Key.

Request body

Response

Saved payment methods

Response

Creates a Stripe SetupIntent for collecting a card without charging it. The client secret is sensitive and is returned only for client-side confirmation.

Response

Saves a payment method after the SetupIntent succeeds. The request supports Idempotency-Key. When a failed automatic top-up turned automatic top-up off, saving a card turns it back on and points it at that card, with no immediate charge. A configuration turned off with PUT /v1/billing/auto-topup, or by deleting its card, stays off.

Request body

Response

Makes an active saved card the default for plan and package charges. The request has no JSON body and supports Idempotency-Key. Like saving a card, it turns back on only a configuration a failed automatic top-up turned off, pointed at that card, with no immediate charge.

Response

Removes a saved card. The response preserves its public record with status: deleted; retries may reuse the same Idempotency-Key.

Response

Automatic top-up

When an automatic top-up fails, enabled turns false without any write of yours, and you are notified once. Saving a card or making one default turns back on only a configuration a failure turned off, pointed at that card; PUT with enabled: true turns it on as well. None of these charges immediately: the next automatic top-up starts when a debit takes the balance from above threshold_brl to at or below it.

Response

Replaces the organization's auto-top-up configuration. An enabled configuration needs an active saved payment method and supports Idempotency-Key. enabled: true turns automatic top-up on, including a configuration a failure turned off; enabled: false keeps it off even when a card is saved later.

Request body

Response

Ledger

Lists debits, credits, and payment completion-fee holds newest first. Only debit entries are spend. A payment fee shows as a payment.initiation debit when the payment is created, a hold for the completion fee, and later either a release that returns the hold or a payment.completion debit that charges it; the hold entry stays listed after it is charged. Each of these entries carries payment_fee with the payment's object and id and the fee reservation id, so you can match them to the payment. Other holds, such as a number's activation fee, appear only as the debit they settle into. Usage and holds default to production; pass environment=sandbox to list sandbox ones, which never move the wallet.

Query

Response

Entry shape

Phone management coverage

Lists cursor-paginated management coverage for numbers imported from your own Salvy account, in the API key's exact project and environment. Coverage is plan while your Standard or Growth plan covers management at no fee, including the whole UTC month in which the plan ends; covered_until is then the 1st after the covered months, when the first fee is due. It is prepaid once one full monthly phone.management.month fee was charged for the current UTC month, with covered_until the next 1st, and none when neither applies, for example while the month is not charged yet, while management is suspended, or after the number was disabled for non-payment at 12:00 UTC on the month’s last UTC day. Sends from a none number fail with phone_service_suspended, and a disabled month reads none until it ends.

next_charge_at and next_charge_brl are the next scheduled charge and one full fee, never prorated. In production they are null when nothing is scheduled: management is suspended, or the number was not in service at the end of the previous month (including a number disabled this month) and your balance is below one full fee. In sandbox, management fees debit nothing: next_charge_brl reads 0.0000 and a sandbox number’s next charge never waits for the balance. summary counts only scheduled charges: retained_count, their monthly_total_brl (0.0000 in sandbox) and the earliest next_charge_at. This read never imports, enrolls, reconnects, or changes a phone. Charged coverage stays in billing history after a management exit.

current_month_payment_status is paid or unpaid for the current enrollment's funded UTC month, using durable unpaid-month evidence, and not_charged without a funded fee. Charged prepaid coverage alone does not prove payment. service_state distinguishes serving, disabled_unpaid_month_end, funding_required and not_serving; provider eligibility, enrollment fences and structural suspension affect service separately from payment. This is not a general send-eligibility verdict.

disable_at is the free-plan month-end deadline for live, unfenced, unended charged coverage whose month stays unpaid; paid plans have no deadline. It remains visible during the release window and is null from the 18:00 UTC cutoff. Provider eligibility and structural suspension do not remove billing disable exposure. Sandbox funded zero fees read paid, otherwise not_charged, with no unpaid state, deadline or unpaid-disable service state. summary.next_charge_brl totals only fees at summary.next_charge_at, or null without a scheduled charge; monthly_total_brl remains the total across all scheduled instants.

Query

Response

Phone renewal decisions (deprecated)

Deprecated. Read the renewal field of GET /v1/phone-numbers and GET /v1/phone-numbers/{id} instead: it reports each rented number's current month (the next charge on the 1st, whether the month is unpaid, and on the free plan when the number is released). See Phone numbers. These two routes keep answering, and are marked deprecated in /openapi.json.

The list returns the renewal cycles recorded by the retired prepaid renewal design, cursor paginated, for the API key's exact project and environment. No new cycle is recorded, so a number rented or renewed under the current policy has none. A cycle's status and actions describe that recorded cycle, not the current month: a terminal cancelled cycle records an operational lifecycle closure, not a non-payment release, and a month charged on its 1st may show as cancelled. A query that fails validation returns 400 invalid_query. Provider details, reservation data, notification recipients, and raw evidence are never returned. This read remains available when production credit is exhausted.

Query

Response

Retrieves one recorded cycle in the same scope. A missing or cross-scope cycle returns phone_renewal_not_found. The optional display identifier is the business phone resource when it is still retained; it is not a notification contact.

Nullable next_renewal_at, release_cutoff_at, grace_selected_at, and grace_ends_at preserve captured provider timing and retained grace. Later invalidation does not erase these historical dates. renewal_warning_48h_at and renewal_warning_24h_at are always null: those warnings are retired. A retained renewed cycle can still have wallet debt.

Response

Dashboard-only billing actions

Custom-amount top-ups, invoice builds, and spend-limit updates are dashboard control-plane workflows, not public customer API endpoints. They are intentionally excluded from /openapi.json.

Invoices

Response

Response