Uma configuração de faturamento é um vínculo no nível da conta entre uma conta do Google Ads e uma conta para pagamentos (também conhecida como configuração de fatura), que determina efetivamente quem é cobrado pelos custos incorridos pelos orçamentos da conta de configuração de faturamento. Cada conta para pagamentos corresponde a uma única fatura.
Sobre as contas para pagamentos
Cada BillingSetup
identifica uma conta para pagamentos
que é faturada pelos custos dos orçamentos da conta. Essa conta
é associada a um perfil
para pagamentos que é
responsável pelas cobranças.
As configurações de faturamento contêm um campo payments_account
e um grupo de campos payments_account_info
que identificam a conta para pagamentos está em uso, incluindo o seguinte:
payments_account_info.payments_account_id
: um ID de 16 dígitos usado para identificar a conta para pagamentos associada à configuração de faturamento.payments_account_info.payments_account_name
: o nome da conta para pagamentos associada à configuração de faturamento. Esse nome é impresso nas faturas mensais.payments_account_info.payments_profile_id
: um ID de 12 dígitos usado para identificar o perfil para pagamentos associado à configuração de faturamento.
Se uma conta para pagamentos estiver qualificada para o faturamento consolidado, várias contas do Google Ads poderão ser agrupadas na mesma fatura definindo as respectivas configurações para usar a mesma conta para pagamentos subjacente.
Criar novas configurações de faturamento
É possível vincular novas configurações de faturamento a contas para pagamentos existentes ou criadas ao mesmo tempo.
Como usar uma conta para pagamentos atual
Para vincular a uma conta para pagamentos existente, defina payments_account
como o ID do recurso de uma conta para pagamentos válida. No entanto, não modifique payments_account_info
.
É possível listar as contas de pagamento disponíveis com o
método PaymentsAccountService.ListPaymentsAccounts
. O
PaymentsAccounts
retornado depende da conta de administrador usada para
autenticação.
Para cada PaymentsAccount
, o ID do administrador
pago está no
campo
paying_manager_customer
.
Como usar uma nova conta para pagamentos
Para vincular a uma nova conta para pagamentos, defina os campos a seguir em
payments_account_info
(não defina payments_account
):
O exemplo abaixo mostra como criar uma nova configuração de faturamento com base em um ID do perfil para pagamentos atual. Conforme indicado acima, isso também criará uma nova conta para pagamentos com o nome 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);
}
Se esta for a primeira configuração de faturamento a ser adicionada a uma conta do Google Ads, o cliente será inscrito no faturamento usando o perfil para pagamentos referenciado.
Status da configuração de faturamento
As novas instâncias de BillingSetup
estão sujeitas a
aprovação antes de entrarem em vigor. Até lá, o
status
vai ficar no estado
PENDING
.
Um BillingSetup
pode estar em um dos seguintes
status
:
Status de configuração do faturamento | Descrição |
---|---|
PENDING |
Aprovação pendente. |
APPROVED_HELD |
Aprovado, mas o primeiro orçamento correspondente não. Isso só pode ocorrer com configurações de faturamento definidas para faturamento mensal. |
APPROVED |
A configuração foi aprovada. |
CANCELLED |
A configuração foi cancelada pelo usuário antes da aprovação. |
Recuperar a configuração de faturamento de uma conta
Assim como a maioria das outras entidades na API Google Ads, um BillingSetup
é buscado consultando o GoogleAdsService.SearchStream
usando uma consulta da linguagem de consulta do Google Ads que especifica quais campos retornar.
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; }
Quando você receber uma referência a uma BillingSetup
,
poderá usá-la para criar uma
AccountBudgetProposal
, conforme descrito em
Orçamento da conta.
Cancelar uma configuração de faturamento pendente
Uma BillingSetup
que ainda não entrou em vigor pode ser
cancelada usando a operação de remoção. As configurações de faturamento só poderão ser canceladas se o
status
for
PENDING
ou se elas forem APPROVED
para iniciar algum tempo no futuro.
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; }