Billing Setup

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 is 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.

Creating new billing setups

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

Using an existing Payments account

To link with an existing Payments account, set payments_account to the resource ID of a valid Payments account. However, don't modify payments_account_info.

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

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

Using 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 example below shows how to create a new billing setup from an existing Payments profile ID. As indicated above, this will also create a new Payments account with the name My New Payments Account.

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

BillingSetupOperation op = BillingSetupOperation.newBuilder().setCreate(bsetup).build();

try (BillingSetupServiceClient billingSetupServiceClient = googleAdsClient
    .getBillingSetupServiceClient()) {

  MutateBillingSetupResponse response =
      billingSetupServiceClient.mutateBillingSetup(Long.toString(customerId), op);
}

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 be in one of the following status:

Billing Setup Status Description
PENDING Pending approval.
APPROVED_HELD Approved but the corresponding first budget has not. 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.

Retrieving an account's billing setup

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

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

Canceling a pending billing setup

A BillingSetup that has not yet taken effect can be canceled using the remove operation. Billing setups can be canceled only if their status are PENDING or if they are APPROVED to start some time in the future.

Previous
Overview
Next
Account budget