Billing setups

  • A billing setup links a Google Ads account to a Payments account, determining who is billed for costs.

  • Each billing setup identifies a Payments account which is associated with a Payments profile responsible for charges.

  • Billing setups contain fields for the Payments account ID, name, and the Payments profile ID.

  • You can create new billing setups using an existing Payments account or by creating a new one simultaneously.

  • New billing setups are subject to approval and can be in various statuses including PENDING, APPROVED_HELD, APPROVED, or CANCELLED.

A billing setup is an account-level link between a Google Ads account and a Payments account (also known as an invoice setup), which effectively determines who is billed for costs incurred by the billing setup's account budgets. Each Payments account corresponds to a single invoice.

About Payments accounts

Each BillingSetup identifies a Payments account that gets invoiced for costs incurred by its account budgets. This Payments account is associated with a Payments profile that is ultimately responsible for charges.

Billing setups contain both a payments_account field and a group of payments_account_info fields that identify the Payments account in use, including the following:

If a Payments account is eligible for consolidated billing, then multiple Google Ads accounts can be grouped in the same invoice by setting their billing setups to use the same underlying Payments account.

Create new billing setups

You can link new billing setups to existing Payments accounts or ones created at the same time.

Use an existing Payments account

To link with an existing Payments account, set payments_account to the resource name of a valid Payments account (for example, customers/{customer_id}/paymentsAccounts/{payments_account_id}). However, don't modify payments_account_info.

You can list available Payments accounts with the PaymentsAccountService.ListPaymentsAccounts method. The PaymentsAccount objects returned depend on the manager account you use for authentication.

For each PaymentsAccount, the resource name of its paying manager is in the paying_manager_customer field.

Use a new Payments account

To link with a new Payments account, set the following fields in payments_account_info (don't set payments_account):

The following example shows how to create a new billing setup from an existing Payments profile ID. As previously indicated, this also creates a new Payments account with the name My New Payments Account.

BillingSetup billingSetup =
    BillingSetup.newBuilder()
        .setPaymentsAccountInfo(
            PaymentsAccountInfo.newBuilder()
                .setPaymentsAccountName("My New Payments Account")
                .setPaymentsProfileId("1234-5678-9012")
                .build())
        .setStartTimeType(TimeTypeEnum.TimeType.NOW)
        .build();

BillingSetupOperation operation =
    BillingSetupOperation.newBuilder().setCreate(billingSetup).build();

try (BillingSetupServiceClient billingSetupServiceClient =
    googleAdsClient.getBillingSetupServiceClient()) {
  MutateBillingSetupResponse response =
      billingSetupServiceClient.mutateBillingSetup(
          Long.toString(customerId), operation);
}

If this is the first billing setup being added to a Google Ads account, this will effectively sign the customer up for billing using the referenced Payments profile.

Billing setup status

New BillingSetup instances are subject to approval before they go into effect. Until then, their status is in a PENDING state.

A BillingSetup can have one of the following status values:

BillingSetupStatus Description
PENDING Pending approval.
APPROVED_HELD Approved, but the corresponding first budget has not been approved. This can only occur for billing setups configured for monthly invoicing.
APPROVED Setup was approved.
CANCELLED Setup was cancelled by the user prior to approval.

Retrieve an account's billing setup

Like most other entities in the Google Ads API, a BillingSetup is fetched by querying GoogleAdsService.Search or GoogleAdsService.SearchStream using a Google Ads Query Language (GAQL) query that specifies which fields to return:

SELECT
  billing_setup.resource_name,
  billing_setup.id,
  billing_setup.status,
  billing_setup.payments_account,
  billing_setup.payments_account_info.payments_account_id,
  billing_setup.payments_account_info.payments_account_name,
  billing_setup.payments_account_info.payments_profile_id,
  billing_setup.payments_account_info.payments_profile_name,
  billing_setup.start_date_time,
  billing_setup.end_date_time,
  billing_setup.end_time_type
FROM billing_setup

Once you obtain a reference to a BillingSetup, you can use it to create an AccountBudgetProposal as described in Account budgets.

Cancel a pending billing setup

A BillingSetup that has not yet taken effect can be canceled by sending a BillingSetupOperation with its remove field set to the resource name of the billing setup (customers/{customer_id}/billingSetups/{billing_setup_id}). Billing setups can be canceled only if their status is PENDING or if they are APPROVED to start some time in the future.

Previous
Billing overview
Next
Account budget