API reference
Billing API reference descriptions are provided in English to preserve the exact published contract.
Configure tax-gated invoicing periods and durable collection retries List settled charges with their message, sender, market and evidence List durable invoices without exposing payment-provider credentials Fetch an invoice and its immutable line references Issue a ledger-backed credit note without rewriting invoice history Re-queue a terminally failed invoice submission Void an invoice issued in error Write a past-due invoice off as uncollectible Read the low-balance alert of each live wallet Set the balance below which the wallet warns its owners Quote one message from the effective immutable pricing fact List payment lifecycle state without exposing payment credentials Submit signed provider pricing evidence and reprocess a pending settlement What this account is charged per message, in force today List the receipts issued for captured wallet top-ups Fetch a top-up receipt with its immutable document List reconciliation discrepancies with their statement evidence Fetch one reconciliation discrepancy and its evidence Resolve a reconciliation case with append-only operator evidence Issue a provider refund against a captured payment List monthly statements for prepaid wallets Fetch a monthly statement with its immutable document Set the tax profile an account's invoices are calculated under (staff only) Start provider-hosted wallet funding List billing wallets and ledger-derived available funds Fetch the effective WABA billing mode and migration state Start a safely gated migration to partner billing Accept partner-billing terms with a single-use MFA step-up grant Revert partner billing only after durable Meta credit-allocation revocation The published platform rate card Configure tax-gated invoicing periods and durable collection retries PUT /v1/accounts/{AC}/billing/automation
putV1AccountsByAcBillingAutomationIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes
Request body (12 fields) Request body Name Type Required Description collectionobject collection.paymentIntentIdstring (uuid) yes collection.retryDelaysHoursinteger (0–8760)[] yes collection.stepUpTokenstring (max 4096 chars) yes currencystring (pattern ^[A-Z]{3}$) yes nextPeriodEndstring (date-time) yes nextPeriodStartstring (date-time) yes providerStatementobject providerStatement.nextPeriodEndstring (date-time) yes providerStatement.nextPeriodStartstring (date-time) yes providerStatement.providerstring (max 128 chars) yes providerStatement.wabaSidstring (WB… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List settled charges with their message, sender, market and evidence GET /v1/accounts/{AC}/billing/charges
getV1AccountsByAcBillingChargesPaginated 200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) fromquery · string (date-time) toquery · string (date-time) senderSidquery · string (WA… SID) campaignSidquery · string (CP… SID) ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List durable invoices without exposing payment-provider credentials GET /v1/accounts/{AC}/billing/invoices
getV1AccountsByAcBillingInvoicesPaginated 200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) statequery · "draft" | "pending_provider" | "open" | "past_due" | "paid" | "void" | "uncollectible" | "failed" ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Fetch an invoice and its immutable line references GET /v1/accounts/{AC}/billing/invoices/{IN}
getV1AccountsByAcBillingInvoicesByIn200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes INpath · string (IN… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Issue a ledger-backed credit note without rewriting invoice history POST /v1/accounts/{AC}/billing/invoices/{IN}/credit-notes
postV1AccountsByAcBillingInvoicesByInCreditNotesIdempotency-Key required 201
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes INpath · string (IN… SID) yes
Request body (8 fields) Request body Name Type Required Description amountMinorstring (pattern ^[1-9][0-9]*$) yes approvalSidstring (AP… SID) currencystring (pattern ^[A-Z]{3}$) yes evidenceobject yes idempotencyKeystring (max 255 chars) yes reasonstring (max 500 chars) yes scaleinteger (0–9) yes taxMinorstring (pattern ^[0-9]+$) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Re-queue a terminally failed invoice submission POST /v1/accounts/{AC}/billing/invoices/{IN}/resubmit
postV1AccountsByAcBillingInvoicesByInResubmitIdempotency-Key required 202
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes INpath · string (IN… SID) yes
Request body (1 fields) Request body Name Type Required Description stepUpTokenstring (max 256 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Void an invoice issued in error POST /v1/accounts/{AC}/billing/invoices/{IN}/void
postV1AccountsByAcBillingInvoicesByInVoidIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes INpath · string (IN… SID) yes
Request body (3 fields) Request body Name Type Required Description evidenceobject yes idempotencyKeystring (max 255 chars) yes reasonstring (max 500 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Write a past-due invoice off as uncollectible POST /v1/accounts/{AC}/billing/invoices/{IN}/write-off
postV1AccountsByAcBillingInvoicesByInWriteOffIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes INpath · string (IN… SID) yes
Request body (3 fields) Request body Name Type Required Description evidenceobject yes idempotencyKeystring (max 255 chars) yes reasonstring (max 500 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Read the low-balance alert of each live wallet GET /v1/accounts/{AC}/billing/low-balance-alerts
getV1AccountsByAcBillingLowBalanceAlerts200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Set the balance below which the wallet warns its owners PUT /v1/accounts/{AC}/billing/low-balance-alerts/{currency}
putV1AccountsByAcBillingLowBalanceAlertsByCurrencyIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes currencypath · string (pattern ^[A-Z]{3}$) yes
Request body (1 fields) Request body Name Type Required Description thresholdstring (pattern ^[0-9][0-9,]*(\.[0-9]+)?$, max 24 chars) | null yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Quote one message from the effective immutable pricing fact POST /v1/accounts/{AC}/billing/message-quote
postV1AccountsByAcBillingMessageQuoteIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes
Request body (5 fields) Request body Name Type Required Description categorystring (pattern ^[A-Z][A-Z0-9_]{0,63}$) yes identifierType"PHONE_E164" | "BSUID" | "USERNAME" yes recipientstring (max 512 chars) yes senderSidstring (WA… SID) yes transport"CLOUD_API" | "MARKETING_MESSAGES"
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List payment lifecycle state without exposing payment credentials GET /v1/accounts/{AC}/billing/payments
getV1AccountsByAcBillingPaymentsPaginated 200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) statequery · string (max 64 chars) ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Submit signed provider pricing evidence and reprocess a pending settlement POST /v1/accounts/{AC}/billing/pricing-remediation/{CS}
postV1AccountsByAcBillingPricingRemediationByCsIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CSpath · string (CS… SID) yes
Request body (11 fields) Request body Name Type Required Description pricingobject yes pricing.billableboolean yes pricing.categorystring (max 64 chars) yes pricing.customerCurrencystring (pattern ^[A-Z]{3}$) yes pricing.marketstring (max 16 chars) yes pricing.pricingModelstring (max 128 chars) yes pricing.pricingType"REGULAR" | "FREE_CUSTOMER_SERVICE" | "FREE_ENTRY_POINT" yes pricing.providerEvidenceobject yes pricing.transportstring (max 64 chars) yes signaturestring (pattern ^v1=[0-9a-f]{64}$) yes stepUpTokenstring (max 256 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
What this account is charged per message, in force today GET /v1/accounts/{AC}/billing/rate-card
getV1AccountsByAcBillingRateCard200
The same effective-dated pricing facts the quote and the settlement read, filtered to what the account holder is actually charged. The admin listing beside this one needs platform:configure, which no customer holds, so until now a business could be charged a rate it had no way to read. Provider cost and margin are deliberately absent: what the platform pays Meta is not the customer's charge and showing it would invite the two to be confused.
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List the receipts issued for captured wallet top-ups GET /v1/accounts/{AC}/billing/receipts
getV1AccountsByAcBillingReceiptsPaginated 200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Fetch a top-up receipt with its immutable document GET /v1/accounts/{AC}/billing/receipts/{RC}
getV1AccountsByAcBillingReceiptsByRc200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes RCpath · string (RC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List reconciliation discrepancies with their statement evidence GET /v1/accounts/{AC}/billing/reconciliation-cases
getV1AccountsByAcBillingReconciliationCasesPaginated 200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) statequery · "open" | "investigating" | "resolved" | "rejected" outcomequery · "amount_mismatch" | "missing_platform_event" | "unexpected_provider_charge" | "missing_provider_status" ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Fetch one reconciliation discrepancy and its evidence GET /v1/accounts/{AC}/billing/reconciliation-cases/{CS}
getV1AccountsByAcBillingReconciliationCasesByCs200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CSpath · string (CS… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Resolve a reconciliation case with append-only operator evidence POST /v1/accounts/{AC}/billing/reconciliation-cases/{CS}/resolve
postV1AccountsByAcBillingReconciliationCasesByCsResolveIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes CSpath · string (CS… SID) yes
Request body (3 fields) Request body Name Type Required Description evidenceobject yes reasonstring (max 500 chars) yes resolution"resolved" | "rejected" yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Issue a provider refund against a captured payment POST /v1/accounts/{AC}/billing/refunds
postV1AccountsByAcBillingRefundsIdempotency-Key required 202
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes
Request body (9 fields) Request body Name Type Required Description amountMinorstring (pattern ^[1-9][0-9]*$) approvalSidstring (AP… SID) yes currencystring (pattern ^[A-Z]{3}$) idempotencyKeystring (max 255 chars) yes invoiceSidstring (IN… SID) paymentIntentIdstring (uuid) reason"duplicate" | "fraudulent" | "requested_by_customer" yes scaleinteger (0–9) stepUpTokenstring (max 256 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List monthly statements for prepaid wallets GET /v1/accounts/{AC}/billing/statements
getV1AccountsByAcBillingStatementsPaginated 200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Fetch a monthly statement with its immutable document GET /v1/accounts/{AC}/billing/statements/{ST}
getV1AccountsByAcBillingStatementsBySt200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes STpath · string (ST… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Set the tax profile an account's invoices are calculated under (staff only) PUT /v1/accounts/{AC}/billing/tax-profile
putV1AccountsByAcBillingTaxProfileIdempotency-Key required 200
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes
Request body (7 fields) Request body Name Type Required Description currencystring (pattern ^[A-Z]{3}$) yes invoiceProviderstring (max 128 chars) yes reasonstring (max 500 chars) yes stepUpTokenstring (max 4096 chars) yes taxCodestring (max 128 chars) yes taxJurisdictionstring (max 128 chars) yes taxProviderstring (max 128 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Start provider-hosted wallet funding POST /v1/accounts/{AC}/billing/top-ups
postV1AccountsByAcBillingTopUpsIdempotency-Key required 202
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes
Request body (5 fields) Request body Name Type Required Description amountMinorstring (pattern ^[1-9][0-9]{0,7}$) yes currencystring (pattern ^[A-Z]{3}$) yes idempotencyKeystring (max 255 chars) yes saveCardForInvoicesboolean stepUpTokenstring (max 4096 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
List billing wallets and ledger-derived available funds GET /v1/accounts/{AC}/billing/wallets
getV1AccountsByAcBillingWalletsPaginated 200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description limitquery · integer (1–100) cursorquery · string (max 2048 chars) currencyquery · string (pattern ^[A-Z]{3}$) commercialModequery · "prepaid" | "postpaid" | "credit_line" | "invoice" | "hybrid" billingStatusquery · string (max 64 chars) dunningStatequery · string (max 64 chars) ACpath · string (AC… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Fetch the effective WABA billing mode and migration state GET /v1/accounts/{AC}/wabas/{WB}/billing-mode
getV1AccountsByAcWabasByWbBillingMode200
Required scope: `billing:read`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes WBpath · string (WB… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Start a safely gated migration to partner billing POST /v1/accounts/{AC}/wabas/{WB}/billing-mode-switch
postV1AccountsByAcWabasByWbBillingModeSwitchIdempotency-Key required 202
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes WBpath · string (WB… SID) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Accept partner-billing terms with a single-use MFA step-up grant POST /v1/accounts/{AC}/wabas/{WB}/billing-mode-switch/accept
postV1AccountsByAcWabasByWbBillingModeSwitchAcceptIdempotency-Key required 200
Required scope: `billing_mode:accept`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes WBpath · string (WB… SID) yes
Request body (2 fields) Request body Name Type Required Description stepUpEvidencestring (max 4096 chars) yes termsVersionstring (max 128 chars) yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
Revert partner billing only after durable Meta credit-allocation revocation POST /v1/accounts/{AC}/wabas/{WB}/billing-mode-switch/revert
postV1AccountsByAcWabasByWbBillingModeSwitchRevertIdempotency-Key required 202
Required scope: `billing:write`.
Parameters
Parameters Name Type Required Description ACpath · string (AC… SID) yes WBpath · string (WB… SID) yes
Request body (2 fields) Request body Name Type Required Description idempotencyKeystring (max 255 chars) yes reason"customer_disconnected" yes
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .
The published platform rate card GET /v1/pricing
getV1PricingNo key needed 200
What ShipMsg charges per delivered message, by category, pricing type, transport, market and currency. Meta bills the business directly for the conversation itself; this fee is the entire ShipMsg charge. Public: no key is needed to read a price.
Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors .