Overview

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 unique prefix: commerce_billingprofile_. Beyond its role as an identifier, it serves as a secure credential that effectively 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.

Environment

Twilio Console 

What You Need To Know

Navigation: Locating Your Billing Group ID in Twilio Console

To manage these credentials, Twilio provides a centralized administrative hub designed for billing and account management within Twilio Console. 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:

1. Log into Twilio Console. 
2. Locate the sidebar navigation (left-hand rail) and click the Blue Folder/Envelope 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 commerce_billingprofile_ is displayed directly below the Billing Group name. Once located, this ID can be transitioned from a manual reference point to a programmatic key for automated data retrieval.

Programmatic Integration: Calling the Usage API

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 specific API endpoint:

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

In this request, the {billingGroupId} acts as a secure credential. You must replace this placeholder 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.

Sample Request Structure

POST /v2/Usage/BillingGroups/commerce_billingprofile_EXAMPLE123/Records

By leveraging this endpoint, administrators can apply specific parameters to tailor the data retrieval to their internal reporting requirements.

Query Optimization: Request Parameters and Filtering

Precision in data retrieval is paramount for effective analysis. By utilizing request parameters, users can isolate specific cost drivers, filter by product categories, and define exact timeframes to avoid data noise.

Note: The timePeriod parameter is an alternative to startDate and endDate; these should not be used in the same request.

The aggregationPeriod is a critical tool for financial granularity. Selecting DAILY allows for the identification of specific usage spikes or trends within a month (vital for spotting anomalies). Conversely, MONTHLY provides a high-level executive view of spend.

Data Interpretation: Analyzing the Usage Response

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.

Record Properties Deconstruction

The API returns records with the following key properties:

Handling Large Datasets (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 (pagination) to ensure no usage records are missed during ingestion.

Sample JSON Response Reference (Example Only)

{
  "asOf": "2025-01-31",
  "records": [
    {
      "productName": "United States-Outbound-LC-MMS",
      "productCategory": "united-states-outbound-lc-mms",
      "startDate": "2025-01-01",
      "endDate": "2025-01-31",
      "usage": {
        "amount": "66505",
        "unit": "segments"
      },
      "price": {
        "amount": 100.5,
        "currency": "USD"
      }
    }
  ],
  "meta": {
    "key": "items",
    "pageSize": 20,
    "previousToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIyIiwicGFnZVNpemUiOiIxMDAifQ",
    "nextToken": "eyJzdGFydE9uIjoiMjAyNi0wMy0wNSIsImVuZE9uIjoiMjAyNi0wMy0wNSIsInBhZ2UiOiIzIiwicGFnZVNpemUiOiIxMDAifQ"
  }
}

While Usage API data provides retrospective insight, it is only an estimate and actual billed usage is reflected on your invoice or usage statement after month-end.

The Twilio Product Catalog

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 productCategory values, users should refer to the Product Catalog documentation.