# 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](https://www.infobip.com/docs/analyze/reports/financial/understand-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](https://www.infobip.com/docs/essentials/api-essentials/api-authorization#api-scopes). - 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](#account-hierarchy-and-visibility). IMPORTANT The 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](https://www.infobip.com/docs/billing-usage-api/billing-data-reference#categories) in the Billing data reference. ___ ## Data finalization IMPORTANT Data 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. NOTE If 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 [#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](https://www.infobip.com/docs/billing-usage-api/query-billing-data) Build your first request, understand filters and aggregation dimensions, and handle the response. [Billing data reference](https://www.infobip.com/docs/billing-usage-api/billing-data-reference) Look up cost fields, billing categories, traffic types by channel, and all available aggregation dimensions. [Financial reports](https://www.infobip.com/docs/analyze/reports/financial/understand-financial-reports) View the same billing data through the web interface with scheduling and export options.