Billing
Inspect pricing and usage, choose a plan, buy message packages, manage saved cards, and configure automatic credit top-ups.
Balance
GET/v1/billing/balance
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "credit_balance" | |
organization_idrequired | string | |
balance_brlrequired | string | |
currencyrequired | "brl" | |
updated_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
Rate-card history
GET/v1/rate-cards
Returns effective-dated BRL rate cards in reverse chronological order. Use the cursor fields to page through historical pricing.
Query
| Field | Type | Notes |
|---|---|---|
limitrequired | integer | range 1..100 |
starting_after | string | |
currency | "brl" |
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "list" | |
datarequired | object[] | |
has_morerequired | boolean | |
next_cursorrequired | string | null |
Current rate card
GET/v1/rate-cards/current
Response
| Field | Type | Notes |
|---|---|---|
idrequired | string | |
objectrequired | "rate_card" | |
namerequired | string | |
currencyrequired | "brl" | |
effective_fromrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
effective_torequired | string<ISO-8601> | null | |
entriesrequired | object[] |
Available plans
GET/v1/billing/plans
Lists the purchasable plan catalog, including each plan's effective transport rate, throughput tier, and phone-number allowance.
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "list" | |
datarequired | object[] |
Current plan
GET/v1/billing/plan
Returns the organization's effective subscription. A status of none represents the free tier.
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "subscription" | |
statusrequired | "active" | "past_due" | "canceled" | "none" | |
plan_offering_idrequired | string | null | |
display_namerequired | string | null | |
billing_railrequired | "stripe_card" | "pix_annual" | null | |
throughput_tierrequired | "starter" | "growth" | "scale" | |
max_phonesrequired | integer | null | |
platform_fee_multiplierrequired | string | |
net_transport_rate_brlrequired | string | |
monthly_fee_brlrequired | string | null | |
current_period_endrequired | string<ISO-8601> | null | |
cancel_at_period_endrequired | boolean |
Subscribe to a plan
POST/v1/billing/plan/subscribe
Requires billing:write and supports Idempotency-Key. Card subscriptions charge the saved default card; annual Pix subscriptions return checkout details in pix.
Request body
| Field | Type | Notes |
|---|---|---|
plan_offering_idrequired | string | |
railrequired | "stripe_card" | "pix_annual" |
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "subscription_checkout" | |
subscriptionrequired | object | |
pixrequired | object | null |
Change the current plan
POST/v1/billing/plan/change
Changes an active subscription to another catalog offering. Reuse one Idempotency-Keyacross 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
| Field | Type | Notes |
|---|---|---|
plan_offering_idrequired | string |
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "subscription" | |
statusrequired | "active" | "past_due" | "canceled" | "none" | |
plan_offering_idrequired | string | null | |
display_namerequired | string | null | |
billing_railrequired | "stripe_card" | "pix_annual" | null | |
throughput_tierrequired | "starter" | "growth" | "scale" | |
max_phonesrequired | integer | null | |
platform_fee_multiplierrequired | string | |
net_transport_rate_brlrequired | string | |
monthly_fee_brlrequired | string | null | |
current_period_endrequired | string<ISO-8601> | null | |
cancel_at_period_endrequired | boolean |
Cancel the current plan
POST/v1/billing/plan/cancel
Schedules cancellation according to the current billing period. The request has no JSON body and supports Idempotency-Key.
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "subscription" | |
statusrequired | "active" | "past_due" | "canceled" | "none" | |
plan_offering_idrequired | string | null | |
display_namerequired | string | null | |
billing_railrequired | "stripe_card" | "pix_annual" | null | |
throughput_tierrequired | "starter" | "growth" | "scale" | |
max_phonesrequired | integer | null | |
platform_fee_multiplierrequired | string | |
net_transport_rate_brlrequired | string | |
monthly_fee_brlrequired | string | null | |
current_period_endrequired | string<ISO-8601> | null | |
cancel_at_period_endrequired | boolean |
Packages
GET/v1/billing/packages
Lists past package purchases and the package offerings currently available to the organization.
Query
| Field | Type | Notes |
|---|---|---|
limitrequired | integer | range 1..100 |
starting_after | string | |
status | "pending" | "succeeded" | "failed" | "refunded" | "expired" |
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "list" | |
datarequired | object[] | |
has_morerequired | boolean | |
next_cursorrequired | string | null | |
available_packagesrequired | object[] |
POST/v1/billing/packages/purchase
Purchases a package with a saved card. This write requires billing:write and supports Idempotency-Key.
Request body
| Field | Type | Notes |
|---|---|---|
package_coderequired | string | len 1..∞ |
payment_method | "card" | |
payment_method_id | string | len 1..∞ |
Response
| Field | Type | Notes |
|---|---|---|
idrequired | string | |
objectrequired | "credit_topup" | |
kindrequired | "cash" | "package" | "x402" | |
statusrequired | "pending" | "succeeded" | "failed" | "refunded" | "expired" | |
amount_brlrequired | string | |
payment_methodrequired | "pix" | "card" | "x402" | "manual" | "promotion" | |
package_coderequired | string | null | |
quota_messagesrequired | integer | null | |
quota_remainingrequired | integer | null | |
stripe_payment_intent_idrequired | string | null | |
stripe_client_secretrequired | string | null | |
provider | "stripe" | "abacate_pay" | "manual" | "promotion" | |
abacate_charge_id | string | null | |
pix_copy_paste | string | null | |
pix_qr_code_base64 | string | null | |
pix_expires_at | string<ISO-8601> | null | |
created_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
completed_atrequired | string<ISO-8601> | null |
Saved payment methods
GET/v1/billing/payment-methods
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "list" | |
datarequired | object[] | |
has_morerequired | "false" | |
next_cursorrequired | null |
POST/v1/billing/payment-methods/setup-intent
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
| Field | Type | Notes |
|---|---|---|
objectrequired | "billing_payment_method_setup_intent" | |
stripe_customer_idrequired | string | |
stripe_setup_intent_idrequired | string | |
stripe_client_secretrequired | string | null |
POST/v1/billing/payment-methods
Saves a payment method after the SetupIntent succeeds. The request supports Idempotency-Key.
Request body
| Field | Type | Notes |
|---|---|---|
stripe_payment_method_idrequired | string | len 1..∞ |
set_default | boolean |
Response
| Field | Type | Notes |
|---|---|---|
idrequired | string | |
objectrequired | "billing_payment_method" | |
typerequired | "card" | |
brandrequired | string | null | |
last4required | string | null | |
exp_monthrequired | integer | null | |
exp_yearrequired | integer | null | |
is_defaultrequired | boolean | |
statusrequired | "active" | "deleted" | |
created_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
updated_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
POST/v1/billing/payment-methods/{payment_method_id}/default
Makes an active saved card the default for plan and package charges. The request has no JSON body and supports Idempotency-Key.
Response
| Field | Type | Notes |
|---|---|---|
idrequired | string | |
objectrequired | "billing_payment_method" | |
typerequired | "card" | |
brandrequired | string | null | |
last4required | string | null | |
exp_monthrequired | integer | null | |
exp_yearrequired | integer | null | |
is_defaultrequired | boolean | |
statusrequired | "active" | "deleted" | |
created_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
updated_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
DELETE/v1/billing/payment-methods/{payment_method_id}
Removes a saved card. The response preserves its public record with status: deleted; retries may reuse the same Idempotency-Key.
Response
| Field | Type | Notes |
|---|---|---|
idrequired | string | |
objectrequired | "billing_payment_method" | |
typerequired | "card" | |
brandrequired | string | null | |
last4required | string | null | |
exp_monthrequired | integer | null | |
exp_yearrequired | integer | null | |
is_defaultrequired | boolean | |
statusrequired | "active" | "deleted" | |
created_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
updated_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
Automatic top-up
GET/v1/billing/auto-topup
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "auto_topup_config" | |
enabledrequired | boolean | |
threshold_brlrequired | string | |
amount_brlrequired | string | |
payment_method_idrequired | string | null | |
last_triggered_atrequired | string<ISO-8601> | null | |
updated_atrequired | string<ISO-8601> | null |
PUT/v1/billing/auto-topup
Replaces the organization's auto-top-up configuration. An enabled configuration needs an active saved payment method and supports Idempotency-Key.
Request body
| Field | Type | Notes |
|---|---|---|
enabledrequired | boolean | |
threshold_brlrequired | string | pattern: ^\d+(\.\d{1,2})?$ |
amount_brlrequired | string | pattern: ^\d+(\.\d{1,2})?$ |
payment_method_id | string | null |
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "auto_topup_config" | |
enabledrequired | boolean | |
threshold_brlrequired | string | |
amount_brlrequired | string | |
payment_method_idrequired | string | null | |
last_triggered_atrequired | string<ISO-8601> | null | |
updated_atrequired | string<ISO-8601> | null |
Ledger
GET/v1/billing/ledger
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "list" | |
datarequired | object[] | |
has_morerequired | boolean | |
next_cursorrequired | string | null |
Entry shape
| Field | Type | Notes |
|---|---|---|
idrequired | string | |
objectrequired | "ledger_entry" | |
typerequired | "debit" | "credit" | |
source_typerequired | "usage" | "credit_topup" | |
source_idrequired | string | |
meter_idrequired | string | null | |
amount_brlrequired | string | |
uncollected_brlrequired | string | null | |
currencyrequired | "brl" | |
environmentrequired | "sandbox" | "production" | null | |
recorded_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |
trace_idrequired | string | null |
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
GET/v1/invoices
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "list" | |
datarequired | object[] | |
has_morerequired | boolean | |
next_cursorrequired | string | null |
GET/v1/invoices/{id}/download
Response
| Field | Type | Notes |
|---|---|---|
objectrequired | "invoice_download" | |
invoice_idrequired | string | |
urlrequired | string | |
expires_atrequired | string<ISO-8601> | pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ |