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:
payments_account_info.payments_account_id
: A 16-digit ID used to identify the Payments account associated with the billing setup.payments_account_info.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
: A 12-digit ID used to identify the Payments profile associated with the billing setup.
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.
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(), billingSetup.getStatus(), billingSetup.getPaymentsAccount(), billingSetup.getPaymentsAccountInfo().getPaymentsAccountId(), billingSetup.getPaymentsAccountInfo().getPaymentsAccountName(), billingSetup.getPaymentsAccountInfo().getPaymentsProfileId(), billingSetup.getPaymentsAccountInfo().getPaymentsProfileName(), billingSetup.getPaymentsAccountInfo().getSecondaryPaymentsProfileId()); } } }
C#
public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsServiceClient. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V13.GoogleAdsService); // Define 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 = new SearchGoogleAdsRequest() { PageSize = PAGE_SIZE, Query = searchQuery, CustomerId = customerId.ToString() }; try { PagedEnumerable<SearchGoogleAdsResponse, GoogleAdsRow> searchPagedResponse = googleAdsService.Search(request); foreach (GoogleAdsRow googleAdsRow in searchPagedResponse) { BillingSetup billingSetup = googleAdsRow.BillingSetup; Console.WriteLine($"Billing setup with ID '{billingSetup.Id}'has status " + $"'{billingSetup.Status}'."); // A missing billing setup will have no payments account information. if (billingSetup.HasPaymentsAccount) { Console.WriteLine( $"\tPayments account: {billingSetup.PaymentsAccount}\n" + "\tPayments account Id: " + $"{billingSetup.PaymentsAccountInfo.PaymentsAccountId}\n" + "\tPayments profile id: " + $"{billingSetup.PaymentsAccountInfo.PaymentsProfileId}\n"); // A pending billing setup will not have values for certain fields. if (billingSetup.Status != BillingSetupStatus.Pending) { Console.WriteLine( "\tPayments account name: " + $"{billingSetup.PaymentsAccountInfo.PaymentsAccountName}\n" + "\tPayments profile name: " + $"{billingSetup.PaymentsAccountInfo.PaymentsProfileName}\n" + "\tSecondary payments profile id: " + $"{billingSetup.PaymentsAccountInfo.SecondaryPaymentsProfileId}"); } } else { Console.WriteLine("Payments account details missing or incomplete."); } } } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } }
PHP
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId) { $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); // Creates a query that retrieves the billing setups. $query = 'SELECT billing_setup.id, ' . ' billing_setup.status, ' . ' 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'; // Issues a search request by specifying page size. $response = $googleAdsServiceClient->search($customerId, $query, ['pageSize' => self::PAGE_SIZE]); // Iterates over all rows in all pages and prints the requested field values for // the billing setup in each row. foreach ($response->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ $paymentAccountInfo = $googleAdsRow->getBillingSetup()->getPaymentsAccountInfo(); if (is_null($paymentAccountInfo)) { printf( 'Found the billing setup with ID %1$d, %3$s' . ' status \'%2$d\' with no payment account info. %3$s', $googleAdsRow->getBillingSetup()->getId(), $googleAdsRow->getBillingSetup()->getStatus(), PHP_EOL ); continue; } printf( 'Found the billing setup with ID %1$d, %8$s' . ' status \'%2$s\', %8$s' . ' payments account ID \'%3$s\', %8$s' . ' payments account name \'%4$s\', %8$s' . ' payments profile ID \'%5$s\', %8$s' . ' payments profile name \'%6$s\', %8$s' . ' secondary payments profile ID \'%7$s\'.%8$s', $googleAdsRow->getBillingSetup()->getId(), BillingSetupStatus::name($googleAdsRow->getBillingSetup()->getStatus()), $paymentAccountInfo->getPaymentsAccountId(), $paymentAccountInfo->getPaymentsAccountName(), $paymentAccountInfo->getPaymentsProfileId(), $paymentAccountInfo->getPaymentsProfileName(), $paymentAccountInfo->getSecondaryPaymentsProfileId() ? $paymentAccountInfo->getSecondaryPaymentsProfileId() : 'None', PHP_EOL ); } }
Python
def main(client, customer_id): ga_service = client.get_service("GoogleAdsService") 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""" stream = ga_service.search_stream(customer_id=customer_id, query=query) print("Found the following billing setup results:") for batch in stream: for row in batch.results: billing_setup = row.billing_setup pai = billing_setup.payments_account_info if pai.secondary_payments_profile_id: secondary_payments_profile_id = ( pai.secondary_payments_profile_id ) else: secondary_payments_profile_id = "None" print( f"Billing setup with ID {billing_setup.id}, " f'status "{billing_setup.status.name}", ' f'payments_account "{billing_setup.payments_account}" ' f"payments_account_id {pai.payments_account_id}, " f'payments_account_name "{pai.payments_account_name}", ' f"payments_profile_id {pai.payments_profile_id}, " f'payments_profile_name "{pai.payments_profile_name}", ' "secondary_payments_profile_id " f"{secondary_payments_profile_id}." )
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.google_ads 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: customer_id, query: 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_info.payments_account_id : "N/A", payments_account_info ? payments_account_info.payments_account_name : "N/A", payments_account_info ? payments_account_info.payments_profile_id : "N/A", payments_account_info ? payments_account_info.payments_profile_name : "N/A", payments_account_info ? payments_account_info.secondary_payments_profile_id : "N/A" ) end end
Perl
sub get_billing_setup { my ($api_client, $customer_id) = @_; # Create a query that retrieves the billing setups. my $search_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"; # Create a search Google Ads request that will retrieve the billing setups # using pages of the specified page size. my $search_request = Google::Ads::GoogleAds::V13::Services::GoogleAdsService::SearchGoogleAdsRequest ->new({ customerId => $customer_id, query => $search_query, pageSize => PAGE_SIZE }); # Get the GoogleAdsService. my $google_ads_service = $api_client->GoogleAdsService(); my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({ service => $google_ads_service, request => $search_request }); # Iterate over all rows in all pages and print the requested field values for # the billing setup in each row. while ($iterator->has_next) { my $google_ads_row = $iterator->next; my $billing_setup = $google_ads_row->{billingSetup}; my $payment_account_info = $billing_setup->{paymentsAccountInfo}; if (!$payment_account_info) { printf "Found the billing setup with ID %d, status '%s' " . "with no payment account info.\n", $billing_setup->{id}, $billing_setup->{status}; next; } printf "Found the 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", $billing_setup->{id}, $billing_setup->{status}, $billing_setup->{paymentsAccount}, $payment_account_info->{paymentsAccountId}, $payment_account_info->{paymentsAccountName}, $payment_account_info->{paymentsProfileId}, $payment_account_info->{paymentsProfileName}, $payment_account_info->{secondaryPaymentsProfileId} ? $payment_account_info->{secondaryPaymentsProfileId} : "None"; } return 1; }
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.
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) { // Get the BillingSetupServiceClient. BillingSetupServiceClient billingSetupService = client.GetService( Services.V13.BillingSetupService); // Create the billing setup resource. String billingSetupResource = ResourceNames.BillingSetup(customerId, billingSetupId); // Construct an operation that will remove the billing setup. BillingSetupOperation operation = new BillingSetupOperation() { Remove = billingSetupResource }; try { // Send the operation in a mutate request. MutateBillingSetupResponse response = billingSetupService.MutateBillingSetup(customerId.ToString(), operation); Console.WriteLine("Removed billing setup with resource name '{0}'.", response.Result.ResourceName); } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } }
PHP
public static function runExample( GoogleAdsClient $googleAdsClient, int $customerId, int $billingSetupId ) { // Creates the resource name of a billing setup to remove. $billingSetupResourceName = ResourceNames::forBillingSetup($customerId, $billingSetupId); // Creates a billing setup operation. $billingSetupOperation = new BillingSetupOperation(); $billingSetupOperation->setRemove($billingSetupResourceName); // Issues a mutate request to remove the billing setup. $billingSetupServiceClient = $googleAdsClient->getBillingSetupServiceClient(); $response = $billingSetupServiceClient->mutateBillingSetup($customerId, $billingSetupOperation); /** @var BillingSetup $removedBillingSetup */ $removedBillingSetup = $response->getResult(); printf( "Removed billing setup with resource name '%s'%s", $removedBillingSetup->getResourceName(), PHP_EOL ); }
Python
def main(client, customer_id, billing_setup_id): billing_setup_service = client.get_service("BillingSetupService") # Create billing setup operation. billing_setup_operation = client.get_type("BillingSetupOperation") billing_setup_operation.remove = billing_setup_service.billing_setup_path( customer_id, billing_setup_id ) # Remove the billing setup. billing_setup_response = billing_setup_service.mutate_billing_setup( customer_id=customer_id, operation=billing_setup_operation ) print( "Removed billing setup " f'"{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.billing_setup resource = client.path.billing_setup(customer_id, billing_setup_id) operation = client.operation.remove_resource.billing_setup(resource) response = billing_setup_service.mutate_billing_setup( customer_id: customer_id, operation: operation, ) puts sprintf("Removed billing_setup %s", response.results.first.resource_name) end
Perl
sub remove_billing_setup { my ($api_client, $customer_id, $billing_setup_id) = @_; # Create the resource name of a billing setup to remove. my $billing_setup_resource_name = Google::Ads::GoogleAds::V13::Utils::ResourceNames::billing_setup( $customer_id, $billing_setup_id); # Create a billing setup operation. my $billing_setup_operation = Google::Ads::GoogleAds::V13::Services::BillingSetupService::BillingSetupOperation ->new({ remove => $billing_setup_resource_name }); # Remove the billing setup. my $billing_setup_response = $api_client->BillingSetupService->mutate({ customerId => $customer_id, operation => $billing_setup_operation }); printf "Removed billing setup with resource name: '%s'.\n", $billing_setup_response->{result}{resourceName}; return 1; }