A billing setup is an account-level link between a Google Ads account and a Payments
account (also known as an [invoice setup](https://support.google.com/google-ads/answer/2375371)), 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup) identifies a Payments account
that gets invoiced for costs incurred by its account budgets. This Payments
account is associated with a [Payments profile](https://support.google.com/google-ads/answer/7268503) that is
ultimately responsible for charges.

[Billing setups](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup) contain both a
[`payments_account`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#payments_account) field and a group of
[`payments_account_info`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#payments_account_info) fields that identify the
Payments account in use, including the following:

- [`payments_account_info.payments_account_id`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup.PaymentsAccountInfo#payments_account_id): A 16-digit ID formatted as a hyphenated string (for example, `"1234-5678-9012-3456"`) used to identify the Payments account associated with the billing setup.
- [`payments_account_info.payments_account_name`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup.PaymentsAccountInfo#payments_account_name): The name of the Payments account associated with the billing setup. This name is printed on monthly invoices.
- [`payments_account_info.payments_profile_id`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup.PaymentsAccountInfo#payments_profile_id): A 12-digit ID formatted as a hyphenated string (for example, `"1234-5678-9012"`) used to identify the Payments profile associated with the billing setup.

If a Payments account is eligible for [consolidated billing](https://support.google.com/google-ads/answer/2375371),
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`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#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`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#payments_account_info).

You can list available Payments accounts with the
[`PaymentsAccountService.ListPaymentsAccounts`](https://developers.google.com/google-ads/api/reference/rpc/v26/PaymentsAccountService/ListPaymentsAccounts) method.
The [`PaymentsAccount`](https://developers.google.com/google-ads/api/reference/rpc/v26/PaymentsAccount) objects returned depend on
the manager account you use for authentication.

For each [`PaymentsAccount`](https://developers.google.com/google-ads/api/reference/rpc/v26/PaymentsAccount), the resource name of
its [paying manager](https://support.google.com/google-ads/answer/9703430) is in the
[`paying_manager_customer`](https://developers.google.com/google-ads/api/reference/rpc/v26/PaymentsAccount#paying_manager_customer) field.

### Use a new Payments account

To link with a new Payments account, set the following fields in
[`payments_account_info`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#payments_account_info) (*don't* set
[`payments_account`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#payments_account)):

- [`payments_account_name`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup.PaymentsAccountInfo#payments_account_name)
- [`payments_profile_id`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup.PaymentsAccountInfo#payments_profile_id)

> [!NOTE]
> **Note:** `payments_account` and `payments_account_info` will both be populated in subsequent retrievals of the billing setup.

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`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup) instances are subject to approval before
they go into effect. Until then, their [`status`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#status) is
in a [`PENDING`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetupStatusEnum.BillingSetupStatus#pending) state.

A [`BillingSetup`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup) can have one of the following
[`status`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#status) values:

| [`BillingSetupStatus`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetupStatusEnum.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`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup) is
fetched by querying [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search) or
[`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/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`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup),
you can use it to create an [`AccountBudgetProposal`](https://developers.google.com/google-ads/api/reference/rpc/v26/AccountBudgetProposal)
as described in [Account budgets](https://developers.google.com/google-ads/api/docs/billing/account-budgets).

## Cancel a pending billing setup

A [`BillingSetup`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup) that has not yet taken effect can be canceled
by sending a [`BillingSetupOperation`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetupOperation) with its
[`remove`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetupOperation#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`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetup#status) is
[`PENDING`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetupStatusEnum.BillingSetupStatus#pending) or if they are [`APPROVED`](https://developers.google.com/google-ads/api/reference/rpc/v26/BillingSetupStatusEnum.BillingSetupStatus#approved) to
start some time in the future.