Google Cloud Billing API

Warnings

• breaking The `google-cloud-billing` library requires Python 3.9 or higher. Older Python versions (<=3.8) are no longer supported. Attempting to use the library with unsupported Python versions will result in installation failures or runtime errors.
  Fix: Upgrade your Python environment to Python 3.9 or a newer supported version.
• gotcha The Cloud Billing API primarily provides management capabilities for billing accounts and access to SKU/pricing catalogs. It does *not* directly provide APIs to fetch detailed cost reports or aggregated billing spend data. For granular cost analysis, you must enable Cloud Billing data export to BigQuery and then query the exported data using a BigQuery client.
  Fix: To access detailed billing costs, configure Cloud Billing export to BigQuery via the Google Cloud Console. Then, use the `google-cloud-bigquery` library to query the exported datasets.
• gotcha Improper management of service account keys (e.g., hardcoding in source, committing to repositories) is a security risk. Google Cloud client libraries, including `google-cloud-billing`, use Application Default Credentials (ADC) to find credentials automatically.
  Fix: For local development, use `gcloud auth application-default login`. For production, leverage attached service accounts on GCP compute resources (e.g., Compute Engine, Cloud Run, Cloud Functions) or Workload Identity Federation for external workloads. Avoid explicit JSON key files where possible.
• deprecated Google Cloud is transitioning its spend-based Committed Use Discounts (CUDs) billing model. Starting July 15, 2025 (and fully by February 5, 2026), CUD savings will be represented as direct discounted prices on your bill, rather than credits. This change might affect how billing data is interpreted or presented.
  Fix: Review the official Google Cloud documentation on upcoming CUD billing model changes. Adjust your cost reporting and analysis tools to account for direct discounted pricing instead of credits. The API client will reflect the underlying data changes.
• gotcha The logging mechanism for `google-cloud-billing` (and other Google Cloud Python libraries) uses standard Python logging. Log events may contain sensitive information, and their occurrence, level, and content are subject to change without being flagged as breaking.
  Fix: If you configure logging for this library, take care to restrict access to logs. Do not depend on the immutability of log events. Consider setting the `GOOGLE_SDK_PYTHON_LOGGING_SCOPE` environment variable for simple configuration or use advanced code-based configuration if strict control is needed.

Install

• pip install google-cloud-billing Install stable version

Imports

• CloudBillingClient

  from google.cloud import billing_v1
  client = billing_v1.CloudBillingClient()

  The primary client class is found within the `billing_v1` submodule, representing version 1 of the Billing API.

Quickstart

This quickstart demonstrates how to instantiate the `CloudBillingClient` and list billing accounts accessible to the authenticated user. It relies on Application Default Credentials (ADC) for authentication. Ensure your local environment is authenticated (e.g., via `gcloud auth application-default login`) and that the service account or user account has the necessary IAM permissions (e.g., `billing.accounts.get`).

import os
from google.cloud import billing_v1

try:
    # Initialize the client using Application Default Credentials
    # Ensure 'gcloud auth application-default login' has been run or
    # GOOGLE_APPLICATION_CREDENTIALS environment variable is set.
    client = billing_v1.CloudBillingClient()

    # List billing accounts accessible by the authenticated user
    # Requires 'billing.accounts.get' permission on the billing account resource.
    print("Listing billing accounts:")
    for account in client.list_billing_accounts():
        print(f"  Name: {account.name}")
        print(f"  Display Name: {account.display_name}")
        print(f"  Open: {account.open}")

    # Example: Get a specific billing account (replace with a valid account ID)
    # billing_account_id = "012345-ABCDEF-789012"
    # billing_account_name = f"billingAccounts/{billing_account_id}"
    # account = client.get_billing_account(name=billing_account_name)
    # print(f"\nDetails for {account.display_name}: {account.name}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure you have set up Application Default Credentials and have sufficient permissions.")
    print("Run 'gcloud auth application-default login' for local development or set the GOOGLE_APPLICATION_CREDENTIALS environment variable.")