--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/usage/billing/billing-group#article headline: Billing Groups description: Learn how to use Twilio Billing Groups to consolidate billing across multiple accounts, locate your Billing Group ID, and retrieve usage data with the Usage API. url: https://www.twilio.com/docs/usage/billing/billing-group inLanguage: en dateModified: 2026-10-20T17:20:50.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Billing Groups The Billing Group ID is a unique alphanumeric key that identifies a specific Twilio Billing Group and always begins with the prefix `billing_group_`. 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: 1. Log in to the [Twilio OneConsole](https://1console.twilio.com/). 2. Locate the sidebar navigation (left-hand rail) and click the **Billing** icon. 3. Select **Billing Dashboard** and then **Overview** from the resulting menu to enter the billing management area. 4. 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 `billing_group_` — 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: ```text POST /v2/Public/Usage/BillingGroups/{billingGroupId}/Records ``` Replace `{billingGroupId}` with the specific `billing_group_` string retrieved from the Console. This ensures the API correctly identifies the billing entity for which you are requesting records. ### Example request ```text POST /v2/Public/Usage/BillingGroups/billing_group_EXAMPLE123/Records ``` ### Request parameters Use request parameters to isolate specific cost drivers, filter by product categories, and define exact timeframes. > \[!NOTE] > > 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 ```json { "updatedOn": "2025-01-31", "records": [ { "productName": "United States-Outbound-LC-MMS", "productCategory": "united-states-outbound-lc-mms", "startOn": "2025-01-01", "endOn": "2025-01-31", "usage": { "amount": 66505, "unit": "segments" }, "price": { "amount": 100.5, "currency": "USD" } } ], "meta": { "key": "records", "pageSize": 20, "previousToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIyIiwicGFnZVNpemUiOiIxMDAifQ", "nextToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIzIiwicGFnZVNpemUiOiIxMDAifQ" } } ``` > \[!WARNING] > > Usage API data is an estimate. Actual billed usage is reflected on your invoice or usage statement after month-end. ## Product catalog The Product Catalog is a comprehensive resource that provides visibility into the entire suite of Twilio products and services, including those your organization may not currently use. It enables you to explore all available offerings and understand the breadth of Twilio's capabilities. To help you reference Twilio's APIs, we include a CSV file with all `productCategory` keys and their friendly names. Use it to find the correct `productCategory` value when you request usage data. [Download the Product Catalog CSV](https://docs-resources.prod.twilio.com/documents/product-catalog-export.csv). ## Related resources * [Usage API Guide](/docs/usage/billing/usage-api-guide) — Advanced guide to authenticating with OAuth, optimizing queries, and analyzing usage responses. * [Twilio Billing Group ID: A Guide to Consolidated Billing and Usage Analytics](https://help.twilio.com/articles/49506588886299-Twilio-Billing-Group-ID-A-Guide-to-Consolidated-Billing-and-Usage-Analytics) — Detailed walkthrough of Billing Group IDs, the Usage API, and analytics on the Twilio Help Center.