Faktur

Invoice bulanan untuk akun Google Ads dapat diambil menggunakan InvoiceService.

Prasyarat

• Mengaktifkan invoice bulanan untuk akun Google Ads. Lihat panduan tentang konfigurasi penagihan dan anggaran akun untuk mempelajari cara mengelola penagihan menggunakan Google Ads API.
• Jika ditetapkan, login-customer-id harus menentukan ID pelanggan akun pengelola yang mengelola akun Google Ads yang invoice-nya Anda ambil. Akun ini diberi label sebagai pengelola pembayaran di UI Google Ads.

Mengambil invoice

Penting: Anda tidak dapat meminta invoice yang diterbitkan sebelum 1 Januari 2019.

Untuk mengambil invoice, Anda harus meminta metode InvoiceService.ListInvoices yang menetapkan semua kolom yang diperlukan di ListInvoicesRequest:

• customer_id: ID pelanggan akun penayangan Google Ads.
• billing_setup: Nama resource penyiapan penagihan dalam format customers/{customer_id}/billingSetups/{billing_setup_id}.
• issue_year: Tahun penerbitan sebagai string empat digit (misalnya, "2025").
• issue_month: Nilai enum MonthOfYear untuk bulan penerbitan.

Anda juga dapat menetapkan kolom opsional berikut:

• include_granular_level_invoice_details: Boolean opsional (defaultnya adalah false). Jika ditetapkan ke true, objek Invoice yang ditampilkan akan menyertakan perincian biaya tingkat kampanye (AccountBudgetSummary.campaign_summaries), biaya peraturan yang diperinci (AccountSummary.regulatory_cost_summaries), dan penyesuaian yang diperinci (AccountSummary.adjustment_summaries).

Jika Anda memiliki konfigurasi penagihan gabungan, Google Ads API akan menampilkan invoice untuk semua pelanggan dalam konfigurasi penagihan yang sama, bukan hanya invoice untuk customer_id yang ditentukan dalam permintaan API.

customer_id harus berupa akun penayangan Google Ads. Untuk mendapatkan semua invoice bagi pengelola pembayaran, buat satu permintaan per akun penayangan Google Ads.

Berikut ini contohnya:

Java

// Issues the request.
ListInvoicesResponse response =
    invoiceServiceClient.listInvoices(
        String.valueOf(customerId),
        ResourceNames.billingSetup(customerId, billingSetupId),
        String.valueOf(oneMonthAgo.getYear()),
        MonthOfYear.valueOf(oneMonthAgo.getMonth().toString()));
GetInvoices.java
      

C#

ListInvoicesResponse response = invoiceServiceClient.ListInvoices(customerId.ToString(),
    ResourceNames.BillingSetup(customerId, billingSetupId),
    // Year must be 2019 or later.
    lastMonthDateTime.Year.ToString("yyyy"),
    lastMonth);
GetInvoices.cs
      

PHP

// Issues the request.
$response = $googleAdsClient->getInvoiceServiceClient()->listInvoices(
    ListInvoicesRequest::build(
        $customerId,
        ResourceNames::forBillingSetup($customerId, $billingSetupId),
        // The year needs to be 2019 or later.
        date('Y', $lastMonth),
        MonthOfYear::value(strtoupper(date('F', $lastMonth)))
    )
);
GetInvoices.php
      

Python

# Issues a request to list invoices.
response = client.get_service("InvoiceService").list_invoices(
    customer_id=customer_id,
    billing_setup=client.get_service("GoogleAdsService").billing_setup_path(
        customer_id, billing_setup_id
    ),
    # The year needs to be 2019 or later, per the docs:
    # https://developers.google.com/google-ads/api/docs/billing/invoice?hl=en#retrieving_invoices
    issue_year=str(last_month.year),
    issue_month=last_month.strftime("%B").upper(),
)
get_invoices.py
      

Ruby

# Issues a request to list invoices.
response = client.service.invoice.list_invoices(
  customer_id: customer_id,
  billing_setup: client.path.billing_setup(customer_id, billing_setup_id),
  # The year needs to be 2019 or later.
  issue_year: last_month.year.to_s,
  # '%^B' option returns the uppercased full month name (e.g. 'JANUARY').
  issue_month: last_month.strftime("%^B").to_sym,
)
get_invoices.rb
      

Perl

# Issue the request.
my $response = $api_client->InvoiceService()->list({
    customerId   => $customer_id,
    billingSetup =>
      Google::Ads::GoogleAds::V26::Utils::ResourceNames::billing_setup(
      ($customer_id, $billing_setup_id)
      ),
    # The year needs to be 2019 or later.
    issueYear  => strftime("%Y", @last_month),
    issueMonth => uc(strftime("%B", @last_month))});
get_invoices.pl
      

curl

# This code example gets invoices for a given billing setup.
#
# Variables:
#   API_VERSION,
#   CUSTOMER_ID,
#   MANAGER_CUSTOMER_ID,
#   OAUTH2_ACCESS_TOKEN:
#     See https://developers.google.com/google-ads/api/rest/auth#request_headers
#     for details.
#
#   BILLING_SETUP_ID: The billing setup resource name of the requested invoices.
#   ISSUE_MONTH: The issue month of the invoice, for example, JANUARY.
#   ISSUE_YEAR: The issue year to retrieve invoices, in yyyy format.
curl -f "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/invoices?billingSetup=${BILLING_SETUP_ID}&issueMonth=${ISSUE_MONTH}&issueYear=${ISSUE_YEAR}" \
--header "Content-Type: application/json" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}"
get_invoices.sh
      

Responsnya adalah objek ListInvoicesResponse yang berisi daftar objek Invoice yang cocok, yang masing-masing berisi sekumpulan besar kolom seperti:

• ID: ID: payments_account_id, payments_profile_id.
• Waktu: issue_date, due_date, service_date_range.
• Jumlah: subtotal_amount_micros, tax_amount_micros, total_amount_micros.
• PDF: pdf_url. Lihat Mendownload PDF invoice untuk mengetahui petunjuknya.
• Histori: corrected_invoice, replaced_invoices.

Kolom ini juga berisi kolom spesifik lainnya jika relevan:

• Penyesuaian: adjustments_subtotal_amount_micros, adjustments_tax_amount_micros, adjustments_total_amount_micros.
• Biaya peraturan: regulatory_costs_subtotal_amount_micros, regulatory_costs_tax_amount_micros, regulatory_costs_total_amount_micros.
• Biaya ekspor: export_charge_subtotal_amount_micros, export_charge_tax_amount_micros, export_charge_total_amount_micros.

Penting: Invoice menggabungkan data semua akun Google Ads dengan konfigurasi penagihan yang menggunakan akun Pembayaran pokok yang sama dengan yang digunakan oleh konfigurasi penagihan yang diminta. Hal ini hanya terjadi jika akun pembayaran yang mendasarinya memenuhi syarat untuk penagihan gabungan.

Mendapatkan detail anggaran

Invoice memberikan informasi mendetail tentang anggaran akun terkait sebagai daftar objek AccountBudgetSummary di kolom account_budget_summaries:

• ID dan metadata: customer, customer_descriptive_name, account_budget, account_budget_name, purchase_order_number.
• Waktu: billable_activity_date_range.
• Jumlah: subtotal_amount_micros, tax_amount_micros, total_amount_micros, invalid_activity_amount_micros, billed_amount_micros, served_amount_micros, overdelivery_amount_micros.
• Pengelompokan aktivitas tidak valid: invalid_activity_summaries, daftar objek InvalidActivitySummary yang berisi original_month_of_service, original_year_of_service, original_invoice_id, original_account_budget_name, original_purchase_order_number, dan amount_micros.
• Pengelompokan tingkat kampanye (diisi saat include_granular_level_invoice_details adalah true): campaign_summaries, daftar objek CampaignSummary yang berisi campaign_description, quantity, unit_of_measure (UnitOfMeasure), dan amount_micros.

Mendapatkan detail akun

Invoice memberikan informasi tentang akun terkait sebagai daftar objek AccountSummary di kolom account_summaries. Subtotal, pajak, dan jumlah total tingkat akun untuk koreksi penagihan, penyesuaian kupon, penyesuaian kelebihan kredit, biaya ekspor, dan biaya peraturan disertakan.

Menetapkan include_granular_level_invoice_details ke true di ListInvoicesRequest juga akan mengisi daftar perincian item berikut di setiap AccountSummary:

• regulatory_cost_summaries: Daftar objek RegulatoryCostSummary dengan regulatory_fee_type (RegulatoryFeeType) dan amount_micros.
• adjustment_summaries: Daftar objek AdjustmentSummary dengan adjustment_description dan amount_micros.

Memahami jumlah

Penting: Perbedaan antara jumlah dalam invoice dan dalam metrik penayangan atau anggaran akun adalah hal yang umum dan wajar. Hal ini disebabkan oleh penyesuaian terlambat yang tidak diperhitungkan dalam invoice yang sudah diterbitkan.

Semua jumlah yang diberikan dalam objek AccountBudgetSummary, AccountSummary, dan Invoice dapat diatribusikan selama periode layanan dan dievaluasi sesuai dengan aturan berikut:

AccountBudgetSummary	Aturan evaluasi
served_amount_micros	$account\_budget\_served$
billed_amount_micros	$account\_budget\_billed$
overdelivery_amount_micros	$account\_budget\_overdelivery$
invalid_activity_amount_micros	$account\_budget\_invalid\_activity$
subtotal_amount_micros	$account\_budget\_pretax$
tax_amount_micros	$account\_budget\_tax$
total_amount_micros	$account\_budget\_pretax + $ $account\_budget\_tax$

AccountSummary	Aturan evaluasi
billing_correction_subtotal_amount_micros	$account\_billing\_correction\_pretax$
coupon_adjustment_subtotal_amount_micros	$account\_coupon\_adjustment\_pretax$
excess_credit_adjustment_subtotal_amount_micros	$account\_excess\_credit\_adjustment\_pretax$
regulatory_costs_subtotal_amount_micros	$account\_regulatory\_costs\_pretax$
export_charge_subtotal_amount_micros	$account\_export\_charge\_pretax$
billing_correction_tax_amount_micros	$account\_billing\_correction\_tax$
coupon_adjustment_tax_amount_micros	$account\_coupon\_adjustment\_tax$
excess_credit_adjustment_tax_amount_micros	$account\_excess\_credit\_adjustment\_tax$
regulatory_costs_tax_amount_micros	$account\_regulatory\_costs\_tax$
export_charge_tax_amount_micros	$account\_export\_charge\_tax$
billing_correction_total_amount_micros	$account\_billing\_correction\_pretax + $ $account\_billing\_correction\_tax$
coupon_adjustment_total_amount_micros	$account\_coupon\_adjustment\_pretax + $ $account\_coupon\_adjustment\_tax$
excess_credit_adjustment_total_amount_micros	$account\_excess\_credit\_adjustment\_pretax + $ $account\_excess\_credit\_adjustment\_tax$
regulatory_costs_total_amount_micros	$account\_regulatory\_costs\_pretax + $ $account\_regulatory\_costs\_tax$
export_charge_total_amount_micros	$account\_export\_charge\_pretax + $ $account\_export\_charge\_tax$
subtotal_amount_micros	$account\_pretax$
tax_amount_micros	$account\_tax$
total_amount_micros	$account\_pretax + $ $account\_tax$

Invoice	Aturan evaluasi
adjustments_subtotal_amount_micros	$\sum_{i=1}^n account\_billing\_correction\_pretax_i + $ $\sum_{i=1}^n account\_coupon\_adjustment\_pretax_i + $ $\sum_{i=1}^n account\_excess\_credit\_adjustment\_pretax_i$
regulatory_costs_subtotal_amount_micros	$\sum_{i=1}^n account\_regulatory\_costs\_pretax_i$
export_charge_subtotal_amount_micros	$\sum_{i=1}^n account\_export\_charge\_pretax_i$
adjustments_tax_amount_micros	$\sum_{i=1}^n account\_billing\_correction\_tax_i + $ $\sum_{i=1}^n account\_coupon\_adjustment\_tax_i + $ $\sum_{i=1}^n account\_excess\_credit\_adjustment\_tax_i$
regulatory_costs_tax_amount_micros	$\sum_{i=1}^n account\_regulatory\_costs\_tax_i$
export_charge_tax_amount_micros	$\sum_{i=1}^n account\_export\_charge\_tax_i$
adjustments_total_amount_micros	$adjustments\_pretax + $ $adjustments\_tax$
regulatory_costs_total_amount_micros	$regulatory\_costs\_pretax + $ $regulatory\_costs\_tax$
export_charge_total_amount_micros	$export\_charge\_pretax + $ $export\_charge\_tax$
subtotal_amount_micros	$adjustments\_pretax + $ $\sum_{i=1}^n account\_budget\_pretax_i$
tax_amount_micros	$adjustments\_tax + $ $regulatory\_costs\_tax + $ $export\_charge\_tax + $ $\sum_{i=1}^n account\_budget\_tax_i$
total_amount_micros	$subtotal\_amount\_micros + $ $regulatory\_costs\_pretax + $ $export\_charge\_pretax + $ $tax\_amount\_micros$

Berikut adalah contoh cara mengiterasi invoice yang diambil:

Java

// Iterates over all invoices retrieved and prints their information.
for (Invoice invoice : response.getInvoicesList()) {
  System.out.printf(
      "- Found the invoice '%s':\n"
          + "  ID (also known as Invoice Number): '%s'\n"
          + "  Type: %s\n"
          + "  Billing setup ID: '%s'\n"
          + "  Payments account ID (also known as Billing Account Number): '%s'\n"
          + "  Payments profile ID (also known as Billing ID): '%s'\n"
          + "  Issue date (also known as Invoice Date): %s\n"
          + "  Due date: %s\n"
          + "  Currency code: %s\n"
          + "  Service date range (inclusive): from %s to %s\n"
          + "  Adjustments: subtotal '%.2f', tax '%.2f', total '%.2f'\n"
          + "  Regulatory costs: subtotal '%.2f', tax '%.2f', total '%.2f'\n"
          + "  Replaced invoices: '%s'\n"
          + "  Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n"
          + "  Corrected invoice: '%s'\n"
          + "  PDF URL: '%s'\n"
          + "  Account budgets: ",
      invoice.getResourceName(),
      invoice.getId(),
      invoice.getType(),
      invoice.getBillingSetup(),
      invoice.getPaymentsAccountId(),
      invoice.getPaymentsProfileId(),
      invoice.getIssueDate(),
      invoice.getDueDate(),
      invoice.getCurrencyCode(),
      invoice.getServiceDateRange().getStartDate(),
      invoice.getServiceDateRange().getEndDate(),
      convertMicrosToCurrency(invoice.getAdjustmentsSubtotalAmountMicros()),
      convertMicrosToCurrency(invoice.getAdjustmentsTaxAmountMicros()),
      convertMicrosToCurrency(invoice.getAdjustmentsTotalAmountMicros()),
      convertMicrosToCurrency(invoice.getRegulatoryCostsSubtotalAmountMicros()),
      convertMicrosToCurrency(invoice.getRegulatoryCostsTaxAmountMicros()),
      convertMicrosToCurrency(invoice.getRegulatoryCostsTotalAmountMicros()),
      invoice.getReplacedInvoicesList(),
      convertMicrosToCurrency(invoice.getSubtotalAmountMicros()),
      convertMicrosToCurrency(invoice.getTaxAmountMicros()),
      convertMicrosToCurrency(invoice.getTotalAmountMicros()),
      invoice.getCorrectedInvoice(),
      invoice.getPdfUrl());
  for (AccountBudgetSummary accountBudgetSummary : invoice.getAccountBudgetSummariesList()) {
    System.out.printf(
        "  - Account budget '%s':\n"
            + "      Name (also known as Account Budget): '%s'\n"
            + "      Customer (also known as Account ID): '%s'\n"
            + "      Customer descriptive name (also known as Account): '%s'\n"
            + "      Purchase order number (also known as Purchase Order): '%s'\n"
            + "      Billing activity date range (inclusive): from %s to %s\n"
            + "      Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n",
        accountBudgetSummary.getAccountBudget(),
        accountBudgetSummary.getAccountBudgetName(),
        accountBudgetSummary.getCustomer(),
        accountBudgetSummary.getCustomerDescriptiveName(),
        accountBudgetSummary.getPurchaseOrderNumber(),
        accountBudgetSummary.getBillableActivityDateRange().getStartDate(),
        accountBudgetSummary.getBillableActivityDateRange().getEndDate(),
        convertMicrosToCurrency(accountBudgetSummary.getSubtotalAmountMicros()),
        convertMicrosToCurrency(accountBudgetSummary.getTaxAmountMicros()),
        convertMicrosToCurrency(accountBudgetSummary.getTotalAmountMicros()));
  }
}
GetInvoices.java
      

C#

// information.
foreach (Invoice invoice in response.Invoices)
{
    Console.WriteLine(
        "- Found the invoice '{0}':\n" +
        "  ID (also known as Invoice Number): '{1}'\n" +
        "  Type: {2}\n" +
        "  Billing setup ID: '{3}'\n" +
        "  Payments account ID (also known as Billing Account Number): '{4}'\n" +
        "  Payments profile ID (also known as Billing ID): '{5}'\n" +
        "  Issue date (also known as Invoice Date): {6}\n" +
        "  Due date: {7}\n" +
        "  Currency code: {8}\n" +
        "  Service date range (inclusive): from {9} to {10}\n" +
        "  Adjustments: subtotal '{11}', tax '{12}', total '{13}'\n" +
        "  Regulatory costs: subtotal '{14}', tax '{15}', total '{16}'\n" +
        "  Replaced invoices: '{17}'\n" +
        "  Amounts: subtotal '{18}', tax '{19}', total '{20}'\n" +
        "  Corrected invoice: '{21}'\n" +
        "  PDF URL: '{22}'\n" +
        "  Account budgets:\n",
        invoice.ResourceName,
        invoice.Id,
        invoice.Type.ToString(),
        invoice.BillingSetup,
        invoice.PaymentsAccountId,
        invoice.PaymentsProfileId,
        invoice.IssueDate,
        invoice.DueDate,
        invoice.CurrencyCode,
        invoice.ServiceDateRange.StartDate,
        invoice.ServiceDateRange.EndDate,
        FormatMicros(invoice.AdjustmentsSubtotalAmountMicros),
        FormatMicros(invoice.AdjustmentsTaxAmountMicros),
        FormatMicros(invoice.AdjustmentsTotalAmountMicros),
        FormatMicros(invoice.RegulatoryCostsSubtotalAmountMicros),
        FormatMicros(invoice.RegulatoryCostsTaxAmountMicros),
        FormatMicros(invoice.RegulatoryCostsTotalAmountMicros),
        invoice.ReplacedInvoices.Count > 0
            ? string.Join("', '", invoice.ReplacedInvoices)
            : "none",
        FormatMicros(invoice.SubtotalAmountMicros),
        FormatMicros(invoice.TaxAmountMicros),
        FormatMicros(invoice.TotalAmountMicros),
        string.IsNullOrEmpty(invoice.CorrectedInvoice)
            ? invoice.CorrectedInvoice
            : "none",
        invoice.PdfUrl);
    foreach (AccountBudgetSummary accountBudgetSummary in
        invoice.AccountBudgetSummaries)
    {
        Console.WriteLine(
            "\t- Account budget '{0}':\n" +
            "\t  Name (also known as Account Budget): '{1}'\n" +
            "\t  Customer (also known as Account ID): '{2}'\n" +
            "\t  Customer descriptive name (also known as Account): '{3}'\n" +
            "\t  Purchase order number (also known as Purchase Order): '{4}'\n" +
            "\t  Billing activity date range (inclusive): from {5} to {6}\n" +
            "\t  Amounts: subtotal '{7}', tax '{8}', total '{9}'\n",
            accountBudgetSummary.AccountBudget,
            accountBudgetSummary.AccountBudgetName ?? "none",
            accountBudgetSummary.Customer,
            accountBudgetSummary.CustomerDescriptiveName ?? "none",
            accountBudgetSummary.PurchaseOrderNumber ?? "none",
            accountBudgetSummary.BillableActivityDateRange.StartDate,
            accountBudgetSummary.BillableActivityDateRange.EndDate,
            FormatMicros(accountBudgetSummary.SubtotalAmountMicros),
            FormatMicros(accountBudgetSummary.TaxAmountMicros),
            FormatMicros(accountBudgetSummary.TotalAmountMicros));
    }
}
GetInvoices.cs
      

PHP

// Iterates over all invoices retrieved and prints their information.
foreach ($response->getInvoices() as $invoice) {
    /** @var Invoice $invoice */
    printf(
        "- Found the invoice '%s':" . PHP_EOL .
        "  ID (also known as Invoice Number): '%s'" . PHP_EOL .
        "  Type: %s" . PHP_EOL .
        "  Billing setup ID: '%s'" . PHP_EOL .
        "  Payments account ID (also known as Billing Account Number): '%s'" . PHP_EOL .
        "  Payments profile ID (also known as Billing ID): '%s'" . PHP_EOL .
        "  Issue date (also known as Invoice Date): %s" . PHP_EOL .
        "  Due date: %s" . PHP_EOL .
        "  Currency code: %s" . PHP_EOL .
        "  Service date range (inclusive): from %s to %s" . PHP_EOL .
        "  Adjustments: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL .
        "  Regulatory costs: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL .
        "  Replaced invoices: '%s'" . PHP_EOL .
        "  Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL .
        "  Corrected invoice: '%s'" . PHP_EOL .
        "  PDF URL: '%s'" . PHP_EOL .
        "  Account budgets:" . PHP_EOL,
        $invoice->getResourceName(),
        $invoice->getId(),
        InvoiceType::name($invoice->getType()),
        $invoice->getBillingSetup(),
        $invoice->getPaymentsAccountId(),
        $invoice->getPaymentsProfileId(),
        $invoice->getIssueDate(),
        $invoice->getDueDate(),
        $invoice->getCurrencyCode(),
        $invoice->getServiceDateRange()->getStartDate(),
        $invoice->getServiceDateRange()->getEndDate(),
        Helper::microToBase($invoice->getAdjustmentsSubtotalAmountMicros()),
        Helper::microToBase($invoice->getAdjustmentsTaxAmountMicros()),
        Helper::microToBase($invoice->getAdjustmentsTotalAmountMicros()),
        Helper::microToBase($invoice->getRegulatoryCostsSubtotalAmountMicros()),
        Helper::microToBase($invoice->getRegulatoryCostsTaxAmountMicros()),
        Helper::microToBase($invoice->getRegulatoryCostsTotalAmountMicros()),
        $invoice->getReplacedInvoices()
            ? implode(
                "', '",
                iterator_to_array($invoice->getReplacedInvoices()->getIterator())
            ) : 'none',
        Helper::microToBase($invoice->getSubtotalAmountMicros()),
        Helper::microToBase($invoice->getTaxAmountMicros()),
        Helper::microToBase($invoice->getTotalAmountMicros()),
        $invoice->getCorrectedInvoice() ?: 'none',
        $invoice->getPdfUrl()
    );
    foreach ($invoice->getAccountBudgetSummaries() as $accountBudgetSummary) {
        /** @var AccountBudgetSummary $accountBudgetSummary */
        printf(
            "  - Account budget '%s':" . PHP_EOL .
            "      Name (also known as Account Budget): '%s'" . PHP_EOL .
            "      Customer (also known as Account ID): '%s'" . PHP_EOL .
            "      Customer descriptive name (also known as Account): '%s'" . PHP_EOL .
            "      Purchase order number (also known as Purchase Order): '%s'" . PHP_EOL .
            "      Billing activity date range (inclusive): from %s to %s" . PHP_EOL .
            "      Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'" . PHP_EOL,
            $accountBudgetSummary->getAccountBudget(),
            $accountBudgetSummary->getAccountBudgetName() ?: 'none',
            $accountBudgetSummary->getCustomer(),
            $accountBudgetSummary->getCustomerDescriptiveName() ?: 'none',
            $accountBudgetSummary->getPurchaseOrderNumber() ?: 'none',
            $accountBudgetSummary->getBillableActivityDateRange()->getStartDate(),
            $accountBudgetSummary->getBillableActivityDateRange()->getEndDate(),
            Helper::microToBase($accountBudgetSummary->getSubtotalAmountMicros()),
            Helper::microToBase($accountBudgetSummary->getTaxAmountMicros()),
            Helper::microToBase($accountBudgetSummary->getTotalAmountMicros())
        );
    }
}
GetInvoices.php
      

Python

    for invoice in response.invoices:
        print(f"""
- Found the invoice {invoice.resource_name}
    ID (also known as Invoice Number): '{invoice.id}'
    Type: {invoice.type_}
    Billing setup ID: '{invoice.billing_setup}'
    Payments account ID (also known as Billing Account Number): '{invoice.payments_account_id}'
    Payments profile ID (also known as Billing ID): '{invoice.payments_profile_id}'
    Issue date (also known as Invoice Date): {invoice.issue_date}
    Due date: {invoice.due_date}
    Currency code: {invoice.currency_code}
    Service date range (inclusive): from {invoice.service_date_range.start_date} to {invoice.service_date_range.end_date}
    Adjustments:
        subtotal {_micros_to_currency(invoice.adjustments_subtotal_amount_micros)}
        tax {_micros_to_currency(invoice.adjustments_tax_amount_micros)}
        total {_micros_to_currency(invoice.adjustments_total_amount_micros)}
    Regulatory costs:
        subtotal {_micros_to_currency(invoice.regulatory_costs_subtotal_amount_micros)}
        tax {_micros_to_currency(invoice.regulatory_costs_tax_amount_micros)}
        total {_micros_to_currency(invoice.regulatory_costs_total_amount_micros)}
    Replaced invoices: {invoice.replaced_invoices.join(", ") if invoice.replaced_invoices else "none"}
    Amounts:
        subtotal {_micros_to_currency(invoice.subtotal_amount_micros)}
        tax {_micros_to_currency(invoice.tax_amount_micros)}
        total {_micros_to_currency(invoice.total_amount_micros)}
    Corrected invoice: {invoice.corrected_invoice or "none"}
    PDF URL: {invoice.pdf_url}
    Account budgets:
    """)
        for account_budget_summary in invoice.account_budget_summaries:
            print(f"""
                  - Account budget '{account_budget_summary.account_budget}':
                      Name (also known as Account Budget): '{account_budget_summary.account_budget_name}'
                      Customer (also known as Account ID): '{account_budget_summary.customer}'
                      Customer descriptive name (also known as Account): '{account_budget_summary.customer_descriptive_name}'
                      Purchase order number (also known as Purchase Order): '{account_budget_summary.purchase_order_number}'
                      Billing activity date range (inclusive):
                        from #{account_budget_summary.billable_activity_date_range.start_date}
                        to #{account_budget_summary.billable_activity_date_range.end_date}
                      Amounts:
                        subtotal '{_micros_to_currency(account_budget_summary.subtotal_amount_micros)}'
                        tax '{_micros_to_currency(account_budget_summary.tax_amount_micros)}'
                        total '{_micros_to_currency(account_budget_summary.total_amount_micros)}'
                """)
get_invoices.py
      

Ruby

# Iterates over all invoices retrieved and prints their information.
response.invoices.each do |invoice|
  puts <<~OUTPUT
  - Found the invoice '#{invoice.resource_name}'
    ID (also known as Invoice Number): '#{invoice.id}'
    Type: #{invoice.type}
    Billing Setup ID: '#{invoice.billing_setup}'
    Payments account ID (also known as Billing Account Number): '#{invoice.payments_account_id}'
    Payments profile ID (also known as Billing ID): '#{invoice.payments_profile_id}'
    Issue date (also known as Invoice Date): #{invoice.issue_date}
    Due date: #{invoice.due_date}
    Currency code: #{invoice.currency_code}
    Service date range (inclusive):
      from #{invoice.service_date_range.start_date}
      to #{invoice.service_date_range.end_date}
    Adjustments:
      subtotal '#{micro_to_base(invoice.adjustments_subtotal_amount_micros)}'
      tax '#{micro_to_base(invoice.adjustments_tax_amount_micros)}'
      total '#{micro_to_base(invoice.adjustments_total_amount_micros)}'
    Regulatory costs:
      subtotal '#{micro_to_base(invoice.regulatory_costs_subtotal_amount_micros)}'
      tax '#{micro_to_base(invoice.regulatory_costs_tax_amount_micros)}'
      total '#{micro_to_base(invoice.regulatory_costs_total_amount_micros)}'
    Replaced invoices: '#{invoice.replaced_invoices ? invoice.replaced_invoices.join(", ") : 'none'}'
    Amounts:
      subtotal '#{micro_to_base(invoice.subtotal_amount_micros)}'
      tax '#{micro_to_base(invoice.tax_amount_micros)}'
      total '#{micro_to_base(invoice.total_amount_micros)}'
    Corrected invoice: '#{invoice.corrected_invoices ? invoice.corrected_invoices : 'none'}'
    PDF URL: '#{invoice.pdf_url}'
    Account budgets:
  OUTPUT
  invoice.account_budget_summaries.each do |account_budget_summary|
    puts <<~OUTPUT
    \tAccount budget '#{account_budget_summary.account_budget}':
    \t  Name (also known as Account Budget): '#{account_budget_summary.account_budget_name}'
    \t  Customer (also known as Account ID): '#{account_budget_summary.customer}'
    \t  Customer descriptive name (also known as Account): '#{account_budget_summary.customer_descriptive_name}'
    \t  Purchase order number (also known as Purchase Order): '#{account_budget_summary.purchase_order_number}'
    \t  Billing activity date range (inclusive):
    \t    from #{account_budget_summary.billable_activity_date_range.start_date}
    \t    to #{account_budget_summary.billable_activity_date_range.end_date}
    \t  Amounts:
    \t    subtotal '#{micro_to_base(account_budget_summary.subtotal_amount_micros)}'
    \t    tax '#{micro_to_base(account_budget_summary.tax_amount_micros)}'
    \t    total '#{micro_to_base(account_budget_summary.total_amount_micros)}'
    OUTPUT
  end
end
get_invoices.rb
      

Perl

# Iterate over all invoices retrieved and print their information.
foreach my $invoice (@$response) {
  printf "- Found the invoice '%s':\n" .
    "  ID (also known as Invoice Number): '%s'\n" .
    "  Type: %s\n" .
    "  Billing setup ID: '%s'\n" .
    "  Payments account ID (also known as Billing Account Number): '%s'\n" .
    "  Payments profile ID (also known as Billing ID): '%s'\n" .
    "  Issue date (also known as Invoice Date): %s\n" .
    "  Due date: %s\n" .
    "  Currency code: %s\n" .
    "  Service date range (inclusive): from %s to %s\n" .
    "  Adjustments: subtotal '%.2f', tax '%.2f', total '%.2f'\n" .
    "  Regulatory costs: subtotal '%.2f', tax '%.2f', total '%.2f'\n" .
    "  Replaced invoices: '%s'\n" .
    "  Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n" .
    "  Corrected invoice: '%s'\n" .
    "  PDF URL: '%s'\n" .
    "  Account budgets:\n",
    $invoice->{resourceName},
    $invoice->{id},
    $invoice->{type},
    $invoice->{billingSetup},
    $invoice->{paymentsAccountId},
    $invoice->{paymentsProfileId},
    $invoice->{issueDate},
    $invoice->{dueDate},
    $invoice->{currencyCode},
    $invoice->{serviceDateRange}{startDate},
    $invoice->{serviceDateRange}{endDate},
    micro_to_base($invoice->{adjustmentsSubtotalAmountMicros}),
    micro_to_base($invoice->{adjustmentsTaxAmountMicros}),
    micro_to_base($invoice->{adjustmentsTotalAmountMicros}),
    micro_to_base($invoice->{regulatoryCostsSubtotalAmountMicros}),
    micro_to_base($invoice->{regulatoryCostsTaxAmountMicros}),
    micro_to_base($invoice->{regulatoryCostsTotalAmountMicros}),
    $invoice->{replacedInvoices}
    ? join(',', @{$invoice->{replacedInvoices}})
    : "none",
    micro_to_base($invoice->{subtotalAmountMicros}),
    micro_to_base($invoice->{taxAmountMicros}),
    micro_to_base($invoice->{totalAmountMicros}),
    $invoice->{correctedInvoice} ? $invoice->{correctedInvoice} : "none",
    $invoice->{pdfUrl};

  foreach my $account_budget_summary (@{$invoice->{accountBudgetSummaries}}) {
    printf "  - Account budget '%s':\n" .
      "      Name (also known as Account Budget): '%s'\n" .
      "      Customer (also known as Account ID): '%s'\n" .
      "      Customer descriptive name (also known as Account): '%s'\n" .
      "      Purchase order number (also known as Purchase Order): '%s'\n" .
      "      Billing activity date range (inclusive): from %s to %s\n" .
      "      Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n",
      $account_budget_summary->{accountBudget},
      $account_budget_summary->{accountBudgetName}
      ? $account_budget_summary->{accountBudgetName}
      : "none",
      $account_budget_summary->{customer},
      $account_budget_summary->{customerDescriptiveName}
      ? $account_budget_summary->{customerDescriptiveName}
      : "none",
      $account_budget_summary->{purchaseOrderNumber}
      ? $account_budget_summary->{purchaseOrderNumber}
      : "none",
      $account_budget_summary->{billableActivityDateRange}{startDate},
      $account_budget_summary->{billableActivityDateRange}{endDate},
      $account_budget_summary->{subtotalAmountMicros},
      $account_budget_summary->{taxAmountMicros},
      $account_budget_summary->{totalAmountMicros};
  }
}
get_invoices.pl
      

curl

Catatan: Meskipun contoh kode REST langsung untuk langkah ini tidak disediakan di sini, Anda dapat melakukannya menggunakan permintaan REST manual.

Lihat dokumentasi antarmuka REST Google Ads API dan halaman referensi khusus metode. Anda harus membuat payload JSON berdasarkan definisi proto.

Referensi Utama:

• Menggunakan REST
• Struktur Antarmuka REST
• Pemetaan Kolom JSON
• Lihat Referensi REST API untuk layanan dan metode tertentu.

Mendownload PDF invoice

Setiap invoice dapat didownload sebagai file PDF. Setelah mengambil Invoice, Anda harus mengirim permintaan HTTP untuk URL yang disimpan di kolom pdf_url. Permintaan ini harus diautentikasi menggunakan Akun Google yang sama dengan yang digunakan untuk mengambil invoice; yaitu, Anda perlu menentukan token akses OAuth yang dibuat menggunakan Akun Google di header permintaan Authorization: Bearer:

curl --request GET \
     --header "Authorization: Bearer ACCESS_TOKEN" \
     "INVOICE_PDF_URL" > FILENAME.pdf

Hasilnya adalah konten PDF invoice yang disimpan dalam file <var>FILENAME</var>.pdf.

Kode error umum

Skenario	Kode Error
Penyiapan penagihan, tahun penerbitan, atau bulan penerbitan tidak ada atau kosong.	RequestError.REQUIRED_FIELD_MISSING
Tidak dapat mengurai penyiapan penagihan, tahun penerbitan, atau bulan penerbitan yang diberikan.	FieldError.INVALID_VALUE
Permintaan ditujukan untuk invoice yang diterbitkan sebelum 1 Januari 2019.	InvoiceError.YEAR_MONTH_TOO_OLD
Permintaan ditujukan untuk pelanggan yang tidak menerima invoice.	InvoiceError.NOT_INVOICED_CUSTOMER
Pengguna tidak memiliki izin untuk melihat invoice konfigurasi penagihan.	AuthorizationError.ACTION_NOT_PERMITTED