Billing Groups
The Billing Group ID is a unique key that identifies a specific Twilio Billing Group. It is characterized by its alphanumeric format 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 provides a structured framework to manage multiple Twilio accounts under a single umbrella. This architecture facilitates three core functional 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.
Twilio provides a centralized administrative hub designed for billing and account management within OneConsole. Accessing your Billing Group ID requires navigating through this interface to find the specific profile linked to your organization.
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.
By integrating usage data directly into internal systems, organizations can track and monitor costs dynamically rather than waiting for end-of-month statements.
Usage data is retrieved through the following API endpoint:
POST /v2/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.
POST /v2/Usage/BillingGroups/commerce_billingprofile_EXAMPLE123/Records
By utilizing request parameters, you can isolate specific cost drivers, filter by product categories, and define exact timeframes to avoid data noise.
Info
The timePeriod parameter is an alternative to startDate and endDate. Don't use them in the same request.
| Parameter | Type | Description |
|---|---|---|
startDate | Date (YYYY-MM-DD) | Filter usage from this date (inclusive). Max range is 365 days. |
endDate | 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. |
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.
The value of the Usage API lies in its structured output, which maps technical usage metrics directly to actual costs. The response provides a clear breakdown of what was used, when it was used, and the associated price.
The API returns records with the following properties:
| Property | Description |
|---|---|
asOf | The latest date/time for the records, formatted as YYYY-MM-DD in UTC. |
productName | A human-readable name of the Twilio product (for example, Outbound MMS). |
productCategory | The category for the product. |
startDate | The first date for which usage is included (UTC, YYYY-MM-DD). |
endDate | 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). |
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.
1{2"asOf": "2025-01-31",3"records": [4{5"productName": "United States-Outbound-LC-MMS",6"productCategory": "united-states-outbound-lc-mms",7"startDate": "2025-01-01",8"endDate": "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": "items",21"pageSize": 20,22"previousToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIyIiwicGFnZVNpemUiOiIxMDAifQ",23"nextToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIzIiwicGFnZVNpemUiOiIxMDAifQ"24}25}
Warning
Usage API data is an estimate. Actual billed usage is reflected on your invoice or usage statement after month-end.
While Usage Records provide a retrospective look at what your organization has already consumed, proactive scaling requires visibility into the full suite of available services. There is a fundamental distinction between these two resources:
- 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 has not yet used. For more details on available
productCategoryvalues, refer to the Product Catalog documentation.