Billing Usage API

The Billing Usage API gives you programmatic access to the same billing data behind your monthly invoices. Query costs on demand, integrate results into your own systems, and build automated reporting pipelines.

Use the Billing Usage API when you need to:

Automate cost reporting pipelines
Integrate billing data into your own dashboards or financial systems
Query across your full account hierarchy on demand
Aggregate costs at month level for period-over-period analysis

Choose how to access billing data

Infobip exposes the same billing-grade data through two surfaces: Financial reports in the web interface and the Billing Usage API for programmatic access. Choose the option that fits your workflow.

Capability	Financial reports	Billing Usage API
Access	Web interface (one-time or recurring)	On-demand, asynchronous
Time granulation	Monthly totals, optional Day breakdown	Day or Month
Filter by campaign reference	No (available as dimension only)	Yes
Name resolution	Shows campaign and template names	IDs only
Export format	XLSX, CSV	JSON (callback)
Scheduling	Recurring (monthly)	On-demand only

For the web interface option, see Financial reports.

How it works

The Billing Usage API uses an asynchronous request-response pattern. You submit a query and Infobip delivers the results to a callback URL on your server when processing completes.

Submit a request
POST to /billing/1/usage/query with your filters, aggregation dimensions, and a callbackUrl pointing to your server.

Receive a request ID
The API immediately returns a requestId. Processing runs asynchronously, so your server does not need to wait.

Receive results at your callback URL
When processing completes, Infobip POSTs the results as JSON to your callbackUrl. Processing time varies based on query complexity and date range.

Access and availability

To use the Billing Usage API, you need:

An API key with the billing:usage:view scope. See API authorization.
A callback URL: A publicly reachable endpoint on your server where Infobip POSTs results when your query completes.

By default, your results include data for your account, related sub-accounts, and all accounts under your company. This cross-account view mirrors your invoicing structure. Sub-account users see only their own data. See Account hierarchy and visibility.

IMPORTANTThe Billing Usage API is not available for legacy account setups. This is a structural limitation; it cannot be enabled on request. If you are unsure whether your account uses a legacy setup, contact your account manager.

Coverage

For the full list of billing category codes, see Categories in the Billing data reference.

Data finalization

IMPORTANTData for the current month is provisional and may change until finalized on the 5th of the following month. Integrate finalized data only into financial or billing systems.

Billing data for the current month is provisional until the month closes. Totals may change until finalized on the 5th of the following month, when the invoice is issued.

Current month data can change due to:

Late-arriving traffic records
Retroactive volume-based discounts
Pricing adjustments

The API response includes a metadata.billingPeriods array that indicates the finalization status of each billing period in your query. Always verify against your invoice before using billing data for financial planning or billing purposes.

NOTEIf you are on a fixed WhatsApp MAU subscription plan, only overage charges are visible in the data. Included user counts are not returned.

Data scope

These constraints apply to all billing data surfaces (financial reports, Billing Usage API):

Retention: Current month and up to 2 months prior
Time zone: UTC. Custom time zones are not supported.
Multi-data center: Data is generated and accessed per data center. Cross-data center aggregation is not supported. To determine where your accounts are hosted, contact your account manager or Support.
Invoicing alignment: Billing data follows the same monthly cycles, currency format, and billing structure as Infobip invoices.

Account hierarchy and visibility

By default, the Billing Usage API returns data across your full account hierarchy: your own account, related sub-accounts, and all accounts under your company. This mirrors your invoicing structure.

Sub-account users see only their own account data. To narrow results to specific accounts, use the accountKeys filter parameter.

Billing Usage API and Metrics API

The Billing Usage API and Metrics API measure different things and are not directly comparable. The Billing Usage API counts only charged messages, and not all channels are billed per message (RCS, for example, is charged per conversation session rather than per individual message). The Metrics API counts all messages regardless of billing status. Time zone configuration may also produce different period boundaries between the two queries.

Use the Billing Usage API for cost reconciliation and the Metrics API for delivery and engagement analysis.

Related pages

Query billing data
Build your first request, understand filters and aggregation dimensions, and handle the response.

Billing data reference
Look up cost fields, billing categories, traffic types by channel, and all available aggregation dimensions.

Financial reports
View the same billing data through the web interface with scheduling and export options.

Query billing data