Configuração de faturamento

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 da 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 recebe a cobrança dos custos gerados pelos orçamentos da conta. Essa conta é associada a um perfil para pagamentos, que é o 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 que a conta para pagamentos está em uso, incluindo o seguinte:

Se uma conta para pagamentos estiver qualificada para o faturamento consolidado, várias contas do Google Ads poderão ser agrupadas na mesma fatura. Para isso, defina as configurações de faturamento para usar a mesma conta para pagamentos.

Criar novas configurações de faturamento

É possível vincular novas configurações de faturamento a contas do Google Payments existentes ou criadas ao mesmo tempo.

Como usar uma conta do Google Payments existente

Para vincular a uma conta para pagamentos existente, defina payments_account como o ID do recurso de uma conta válida do Payments. No entanto, don't 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 que você usa para autenticação.

Para cada PaymentsAccount, o ID do administrador pagador está no campo paying_manager_customer.

Usar uma nova conta do Google Payments

Para vincular a uma nova conta para pagamentos, defina os campos a seguir em payments_account_info (don't definir payments_account):

O exemplo abaixo mostra como criar uma nova configuração de faturamento com base em um ID do perfil para pagamentos. Conforme indicado acima, isso também criará uma nova conta de 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 adicionada a uma conta do Google Ads, o cliente será inscrito pelo faturamento usando o perfil para pagamentos mencionado.

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 estará em um estado PENDING.

Um BillingSetup pode estar em um destes 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 para configurações de faturamento definidas para o faturamento mensal.
APPROVED A configuração foi aprovada.
CANCELLED A configuração foi cancelada pelo usuário antes da aprovação.

Como recuperar a configuração de faturamento de uma conta

Assim como a maioria das outras entidades na API Google Ads, é possível consultar um BillingSetup consultando a GoogleAdsService.SearchStream com uma consulta da linguagem de consulta do Google Ads que especifica quais campos serão retornados.

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.V11.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::V11::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;
}
      

Depois de conseguir uma referência a uma BillingSetup, use-a 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 status for PENDING ou se forem APPROVED para iniciar algum horário 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.V11.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::V11::Utils::ResourceNames::billing_setup(
    $customer_id, $billing_setup_id);

  # Create a billing setup operation.
  my $billing_setup_operation =
    Google::Ads::GoogleAds::V11::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;
}