Billing Groups

The Billing Group ID is a unique alphanumeric key that identifies a specific Twilio Billing Group and always begins with the prefix commerce_billingprofile_. Beyond its role as an identifier, it serves as a secure credential that acts as a username for administrative and API-driven tasks.

A Billing Group lets you manage multiple Twilio accounts under a single umbrella, providing three core advantages:

Shared Pricing: Apply consistent pricing models across all sub-accounts within the group.
Consolidated Invoicing: Receive a single, unified bill for all accounts, simplifying accounts payable workflows.
Unified Payment Methods: Maintain a single set of payment methods for the entire group, reducing administrative overhead.

Find your Billing Group ID in OneConsole

You can find your Billing Group ID in the billing and account management section of OneConsole.

To locate your ID, follow these steps:

Log in to the Twilio OneConsole.
Locate the sidebar navigation (left-hand rail) and click the Billing icon.
Select Billing Dashboard and then Overview from the resulting menu to enter the billing management area.
Navigate to the Billing Groups list, which displays all groups associated with your organization.

When viewing the list of Billing Groups, look for the specific group name you wish to analyze. The Billing Group ID — the string beginning with commerce_billingprofile_ — is displayed directly below the Billing Group name. Once located, this ID can be used as a programmatic key for automated data retrieval.

Retrieve usage data with the API

Integrate usage data directly into your internal systems to track and monitor costs dynamically, rather than waiting for end-of-month statements.

Endpoint

Retrieve usage data through the following API endpoint:

POST /v2/Public/Usage/BillingGroups/{billingGroupId}/Records

Replace {billingGroupId} with the specific commerce_billingprofile_ string retrieved from the Console. This ensures the API correctly identifies the billing entity for which you are requesting records.

Example request

POST /v2/Public/Usage/BillingGroups/commerce_billingprofile_EXAMPLE123/Records

Request parameters

Use request parameters to isolate specific cost drivers, filter by product categories, and define exact timeframes.

(information)

Info

The timePeriod parameter is an alternative to startOn and endOn. Don't use them in the same request.

Parameter	Type	Description
`startOn`	Date (`YYYY-MM-DD`)	Filter usage from this date (inclusive). Max range is 365 days.
`endOn`	Date (`YYYY-MM-DD`)	Filter usage to this date (inclusive). Max range is 365 days.
`timePeriod`	Enum: `YESTERDAY`, `THIS_MONTH`, `LAST_MONTH`, `THIS_YEAR`	A predefined filter as an alternative to custom start and end dates.
`productCategory`	String	Isolate usage data for a specific Twilio product category.
`aggregationPeriod`	Enum: `DAILY`, `MONTHLY`	Define how records are grouped within the requested range.
`pageSize`	Integer	Limit the number of items returned in a single response (1-1000).

The aggregationPeriod is a critical tool for financial granularity. Use DAILY aggregation to identify specific usage spikes or trends within a month (vital for spotting anomalies). Use MONTHLY for a high-level executive view of spend.

Understand the response

The response maps usage metrics directly to costs, providing a breakdown of what was used, when it was used, and the associated price.

The API returns records with the following properties:

Property	Description
`updatedOn`	The date the data was last updated, formatted as `YYYY-MM-DD` in UTC. The latest possible value is the day before the request date, because the current day's data is still being computed.
`productName`	A human-readable name of the Twilio product (for example, Outbound MMS).
`productCategory`	The category for the product.
`startOn`	The first date for which usage is included (UTC, `YYYY-MM-DD`).
`endOn`	The last date for which usage is included (UTC, `YYYY-MM-DD`).
`usage`	The volume used (`amount`) and the metric (`unit`, for example, segments, messages).
`price`	The total cost (`amount`) and the ISO 4217 currency code (for example, USD, GBP, EUR).

Pagination

For organizations with high volume, the meta section of the response is vital for data management. It includes pageSize to define the limit of the current view, along with previousToken and nextToken. These tokens allow systems to iterate through large datasets to ensure no usage records are missed during ingestion.

Example response

1{
2  "updatedOn": "2025-01-31",
3  "records": [
4    {
5      "productName": "United States-Outbound-LC-MMS",
6      "productCategory": "united-states-outbound-lc-mms",
7      "startOn": "2025-01-01",
8      "endOn": "2025-01-31",
9      "usage": {
10        "amount": 66505,
11        "unit": "segments"
12      },
13      "price": {
14        "amount": 100.5,
15        "currency": "USD"
16      }
17    }
18  ],
19  "meta": {
20    "key": "records",
21    "pageSize": 20,
22    "previousToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIyIiwicGFnZVNpemUiOiIxMDAifQ",
23    "nextToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIzIiwicGFnZVNpemUiOiIxMDAifQ"
24  }
25}

(warning)

Warning

Usage API data is an estimate. Actual billed usage is reflected on your invoice or usage statement after month-end.

Product catalog

Usage Records and the Product Catalog serve two distinct purposes:

Usage Records: Retrospective data that captures historical consumption and costs for products you have actively deployed.
Product Catalog: A prospective resource that offers visibility into the full range of Twilio offerings, including services your organization hasn't used. For more details on available productCategory values, refer to the Product Catalog documentation.