Billing Setup

A billing setup is an account-level link between a Google Ads account and a Payments account, 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 which 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 onto the same invoice by setting their billing setups to use the same underlying Payments account.

Creating new billing setups

New billing setups can either be linked to an existing Payments account, or you can create a new Payments account at the same time as creating a new billing setup.

To sign up with an existing Payments account, set the payments_account to the resource ID of a valid Payments account (payments_account_info should not be set).

You can list available payment accounts for your signed in user by using the PaymentsAccountService.ListPaymentsAccounts method.

To sign up with a new Payments account, set the following fields in payments_account_info (payments_account should not be set):

  • payments_account_name
  • payments_profile_id

Note that payments_account and payments_account_info will both be populated when subsequently getting the billing setup.

The example below illustrates 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(StringValue.of("My New Payments Account"))
        .setPaymentsProfileId(StringValue.of("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, before which they will be in a PENDING state. A BillingSetup can be in one of the following status.

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 setups

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

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  // Defines a GAQL query to retrieve all billing setup information.
  String searchQuery = "SELECT 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.payments_account_info.secondary_payments_profile_id "
      + "FROM billing_setup";

  // Creates a request that will retrieve all billing setups using pages of the specified
  // page size.
  SearchGoogleAdsRequest request = SearchGoogleAdsRequest.newBuilder()
      .setCustomerId(String.valueOf(customerId)).setPageSize(PAGE_SIZE).setQuery(
          searchQuery).build();

  try (GoogleAdsServiceClient googleAdsServiceClient = googleAdsClient.getLatestVersion()
      .createGoogleAdsServiceClient()) {
    // Issues the search request.
    SearchPagedResponse response = googleAdsServiceClient.search(request);

    // Iterates over all rows in all pages and prints the requested field values for the billing
    // setup in each row.
    for (GoogleAdsRow googleAdsRow : response.iterateAll()) {
      BillingSetup billingSetup = googleAdsRow.getBillingSetup();
      System.out.printf(
          "Billing setup with ID '%d', "
              + "status '%s', "
              + "payments_account '%s', "
              + "payments_account_id '%s', "
              + "payments_account_name '%s', "
              + "payments_profile_id '%s', "
              + "payments_profile_name '%s', "
              + "secondary_payments_profile_id '%s'.%n",
          billingSetup.getId().getValue(),
          billingSetup.getStatus(),
          billingSetup.getPaymentsAccount().getValue(),
          billingSetup.getPaymentsAccountInfo().getPaymentsAccountId().getValue(),
          billingSetup.getPaymentsAccountInfo().getPaymentsAccountName().getValue(),
          billingSetup.getPaymentsAccountInfo().getPaymentsProfileId().getValue(),
          billingSetup.getPaymentsAccountInfo().getPaymentsProfileName().getValue(),
          billingSetup.getPaymentsAccountInfo().getSecondaryPaymentsProfileId().getValue());
    }
  }
}

C#

public void Run(GoogleAdsClient client, long customerId)

PHP

public static function main()

Python

def main(client, customer_id, page_size):
    ga_service = client.get_service('GoogleAdsService', version='v1')

    query = (
        'SELECT 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.payments_account_info.secondary_payments_profile_id '
        'FROM billing_setup')

    results = ga_service.search(customer_id, query=query, page_size=page_size)

    try:
        # Use the enum type to determine the enum name from the value.
        billing_setup_status_enum = (
            client.get_type('BillingSetupStatusEnum', version='v1')
                .BillingSetupStatus)

        print('Found the following billing setup results:')
        for row in results:
            billing_setup = row.billing_setup
            payments_account_info = billing_setup.payments_account_info
            print('Billing setup with ID "%s", status "%s", '
                  'payments_account "%s", payments_account_id "%s", '
                  'payments_account_name "%s", payments_profile_id "%s", '
                  'payments_profile_name "%s", '
                  'secondary_payments_profile_id "%s".'
                  % (billing_setup.id.value,
                     billing_setup_status_enum.Name(billing_setup.status),
                     billing_setup.payments_account.value,
                     payments_account_info.payments_account_id.value,
                     payments_account_info.payments_account_name.value,
                     payments_account_info.payments_profile_id.value,
                     payments_account_info.payments_profile_name.value,
                     payments_account_info.secondary_payments_profile_id.value))
    except google.ads.google_ads.errors.GoogleAdsException as ex:
        print('Request with ID "%s" failed with status "%s" and includes the '
              'following errors:' % (ex.request_id, ex.error.code().name))
        for error in ex.failure.errors:
            print('\tError with message "%s".' % error.message)
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print('\t\tOn field: %s' % field_path_element.field_name)
        sys.exit(1)

Ruby

def get_billing_setup(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  ga_service = client.service(:GoogleAds)

  search_query = <<~QUERY
    SELECT 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.payments_account_info.secondary_payments_profile_id
    FROM billing_setup
  QUERY

  response = ga_service.search(
    customer_id,
    search_query,
    page_size: PAGE_SIZE
  )

  response.each do |row|
    billing_setup = row.billing_setup
    payments_account_info = billing_setup.payments_account_info

    puts sprintf('Billing setup with ID "%s", status "%s",'\
        ' payments_account "%s", payments_account_id "%s",'\
        ' payments_account_name "%s", payments_profile_id "%s",'\
        ' payments_profile_name "%s", secondary_payments_profile_id "%s"',
        billing_setup.id,
        billing_setup.status,
        billing_setup.payments_account,
        payments_account_info.payments_account_id,
        payments_account_info.payments_account_name,
        payments_account_info.payments_profile_id,
        payments_account_info.payments_profile_name,
        payments_account_info.secondary_payments_profile_id
    )
  end
end

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

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 they are PENDING or if they are APPROVED to start some time in the future.

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId, long billingSetupId) {
  // Formats the customerId and billingSetupId into a resource name.
  String billingSetupResourceName = ResourceNames.billingSetup(customerId, billingSetupId);

  // Constructs an operation that will remove the billing setup.
  BillingSetupOperation operation = BillingSetupOperation.newBuilder()
      .setRemove(billingSetupResourceName)
      .build();

  try (BillingSetupServiceClient billingSetupServiceClient = googleAdsClient.getLatestVersion()
      .createBillingSetupServiceClient()) {
    // Sends the operation in a mutate request.
    MutateBillingSetupResponse response = billingSetupServiceClient
        .mutateBillingSetup(String.valueOf(customerId), operation);

    System.out.printf("Removed billing setup with resource name '%s'.%n",
        response.getResult().getResourceName());
  }
}

C#

public void Run(GoogleAdsClient client, long customerId, long billingSetupId)

PHP

public static function main()

Python

def main(client, customer_id, billing_setup_id):
    billing_setup_service = client.get_service('BillingSetupService',
                                               version='v1')

    # Create billing setup operation.
    billing_setup_operation = client.get_type('BillingSetupOperation',
                                              version='v1')
    billing_setup_operation.remove = billing_setup_service.billing_setup_path(
        customer_id, billing_setup_id)

    # Remove the billing setup.
    try:
        billing_setup_response = billing_setup_service.mutate_billing_setup(
            customer_id, billing_setup_operation)
    except google.ads.google_ads.errors.GoogleAdsException as ex:
        print('Request with ID "%s" failed with status "%s" and includes the '
              'following errors:' % (ex.request_id, ex.error.code().name))
        for error in ex.failure.errors:
            print('\tError with message "%s".' % error.message)
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print('\t\tOn field: %s' % field_path_element.field_name)
        sys.exit(1)

    print('Removed billing setup %s.'
          % billing_setup_response.results[0].resource_name)

Ruby

def remove_billing_setup(customer_id, billing_setup_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  billing_setup_service = client.service(:BillingSetup)

  resource =  client.path.billing_setup(customer_id, billing_setup_id)

  response = billing_setup_service.mutate_billing_setups(customer_id,
      [{remove: resource}])

  puts sprintf("Removed billing_setup %s", response.results.first.resource_name)
end

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.