Monthly invoices for a Google Ads account can be retrieved using the
[`InvoiceService`](https://developers.google.com/google-ads/api/reference/rpc/v26/InvoiceService.md.txt).

## Prerequisites

- Have [monthly invoicing](https://support.google.com/google-ads/answer/2375377) enabled for the Google Ads account. See the guides on account [billing setups](https://developers.google.com/google-ads/api/docs/billing/billing-setups.md.txt) and [budgets](https://developers.google.com/google-ads/api/docs/billing/account-budgets.md.txt) to learn how to manage billing using the Google Ads API.
- If set, [`login-customer-id`](https://developers.google.com/google-ads/api/docs/concepts/call-structure.md.txt#cid) must specify the customer ID of a manager account that is managing the Google Ads account for which you're retrieving invoices. This is labeled as the [paying manager](https://support.google.com/google-ads/answer/9703430) in the Google Ads UI.

## Retrieve invoices

> [!IMPORTANT]
> **Important:** You cannot request invoices issued before January 1, 2019.

To retrieve invoices, you must request the
[`InvoiceService.ListInvoices` method](https://developers.google.com/google-ads/api/reference/rpc/v26/InvoiceService/ListInvoices.md.txt)
setting all the required fields in the
[`ListInvoicesRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListInvoicesRequest.md.txt):

- `customer_id`: The customer ID of the Google Ads serving account.
- `billing_setup`: The billing setup resource name in the format `customers/{customer_id}/billingSetups/{billing_setup_id}`.
- `issue_year`: The issue year as a four-digit string (for example, `"2025"`).
- `issue_month`: The [`MonthOfYear`](https://developers.google.com/google-ads/api/reference/rpc/v26/MonthOfYearEnum.MonthOfYear.md.txt) enum value for the issue month.

You can also set the following optional field:

- `include_granular_level_invoice_details`: Optional boolean (defaults to `false`). When set to `true`, the returned [`Invoice`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.md.txt) objects include campaign-level cost breakdowns (`AccountBudgetSummary.campaign_summaries`), itemized regulatory costs (`AccountSummary.regulatory_cost_summaries`), and itemized adjustments (`AccountSummary.adjustment_summaries`).

If you have a consolidated billing setup, the Google Ads API returns invoices for all
customers under the same billing setup, not just the invoice for the
`customer_id` specified in the API request.

The `customer_id` must be a Google Ads serving account. To get all the
invoices for a paying manager, make one request per Google Ads serving
account.

Here is an example:


### Java

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

### C#

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

### PHP

```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)))
    )
);
      
```

### Python

```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(),
)
      
```

### Ruby

```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,
)
      
```

### Perl

```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))});
      
```

### curl

```console
# 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}"
      
```

<br />

The response is a [`ListInvoicesResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListInvoicesResponse.md.txt)
object that contains the list of matching [`Invoice`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.md.txt)
objects, each of which contains a large set of fields such as:

- IDs: `payments_account_id`, `payments_profile_id`.
- Time: `issue_date`, `due_date`, `service_date_range`.
- Amounts: `subtotal_amount_micros`, `tax_amount_micros`, `total_amount_micros`.
- PDF: `pdf_url`. See [Download an invoice PDF](https://developers.google.com/google-ads/api/docs/billing/invoice.md.txt#pdf) for instructions.
- History: `corrected_invoice`, `replaced_invoices`.

It also contains other specific fields when relevant:

- [Adjustments](https://support.google.com/google-ads/answer/1704323): `adjustments_subtotal_amount_micros`, `adjustments_tax_amount_micros`, `adjustments_total_amount_micros`.
- [Regulatory costs](https://support.google.com/google-ads/answer/2375370): `regulatory_costs_subtotal_amount_micros`, `regulatory_costs_tax_amount_micros`, `regulatory_costs_total_amount_micros`.
- [Export charges](https://support.google.com/google-ads/answer/13674500): `export_charge_subtotal_amount_micros`, `export_charge_tax_amount_micros`, `export_charge_total_amount_micros`.

> [!IMPORTANT]
> **Important:** An invoice combines data of all the Google Ads accounts with billing setups that use the same underlying Payments account as the one used by the requested billing setup. This only happens when the underlying Payments account is eligible for [consolidated billing](https://support.google.com/google-ads/answer/2392966).

### Get budget details

An [`Invoice`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.md.txt) provides detailed information about related
[account budgets](https://developers.google.com/google-ads/api/docs/billing/account-budgets.md.txt) as a list of
[`AccountBudgetSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.AccountBudgetSummary.md.txt) objects
in the `account_budget_summaries` field:

- IDs and metadata: `customer`, `customer_descriptive_name`, `account_budget`, `account_budget_name`, `purchase_order_number`.
- Time: `billable_activity_date_range`.
- Amounts: `subtotal_amount_micros`, `tax_amount_micros`, `total_amount_micros`, `invalid_activity_amount_micros`, `billed_amount_micros`, `served_amount_micros`, `overdelivery_amount_micros`.
- Invalid activity breakdowns: `invalid_activity_summaries`, a list of [`InvalidActivitySummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.InvalidActivitySummary.md.txt) objects containing `original_month_of_service`, `original_year_of_service`, `original_invoice_id`, `original_account_budget_name`, `original_purchase_order_number`, and `amount_micros`.
- Campaign-level breakdowns (populated when `include_granular_level_invoice_details` is `true`): `campaign_summaries`, a list of [`CampaignSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.CampaignSummary.md.txt) objects containing `campaign_description`, `quantity`, `unit_of_measure` ([`UnitOfMeasure`](https://developers.google.com/google-ads/api/reference/rpc/v26/UnitOfMeasureEnum.UnitOfMeasure.md.txt)), and `amount_micros`.

### Get account details

An [`Invoice`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.md.txt) provides information about related
[accounts](https://developers.google.com/google-ads/api/docs/account-management/overview.md.txt) as a list of
[`AccountSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.AccountSummary.md.txt) objects
in the `account_summaries` field. It includes account-level subtotal, tax, and
total amounts for billing corrections, coupon adjustments, excess credit
adjustments, export charges, and regulatory costs.

Setting `include_granular_level_invoice_details` to `true` in
`ListInvoicesRequest` also populates the following itemized breakdown lists on
each [`AccountSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.AccountSummary.md.txt):

- `regulatory_cost_summaries`: A list of [`RegulatoryCostSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.RegulatoryCostSummary.md.txt) objects with `regulatory_fee_type` ([`RegulatoryFeeType`](https://developers.google.com/google-ads/api/reference/rpc/v26/RegulatoryFeeTypeEnum.RegulatoryFeeType.md.txt)) and `amount_micros`.
- `adjustment_summaries`: A list of [`AdjustmentSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.AdjustmentSummary.md.txt) objects with `adjustment_description` and `amount_micros`.

### Understand amounts

> [!IMPORTANT]
> **Important:** Differences between amounts in invoices and in serving [metrics](https://developers.google.com/google-ads/api/fields/v26/metrics.md.txt) or [account budgets](https://developers.google.com/google-ads/api/fields/v26/account_budget.md.txt) are common and expected. This is due to late [adjustments](https://support.google.com/google-ads/answer/1704323) that are *not* taken into account in already issued invoices.

All the amounts provided in [`AccountBudgetSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.AccountBudgetSummary.md.txt),
[`AccountSummary`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.AccountSummary.md.txt), and
[`Invoice`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.md.txt) objects are attributable during their service
periods and are evaluated according to these rules:

| `AccountBudgetSummary` | Evaluation rule |
|---|---|
| `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` | Evaluation rule |
|---|---|
| `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` | Evaluation rule |
|---|---|
| `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$ |

Here is an example of how the retrieved invoices can be iterated on:


### Java

```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()));
  }
}
      
```

### C#

```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));
    }
}
      
```

### PHP

```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())
        );
    }
}
      
```

### Python

```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)}'
                """)
      
```

### Ruby

```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
      
```

### Perl

```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};
  }
}
      
```

### curl

> [!NOTE]
> **Note:** While a direct REST code sample for this step isn't provided here, you can achieve this using a manual REST request.   
>
> Refer to the Google Ads API REST interface documentation and the method-specific reference pages. You will need to construct the JSON payload based on the proto definitions.   
>
> Key Resources:
>
> - [Using REST](https://developers.google.com/google-ads/api/rest/overview.md.txt)
> - [REST Interface Structure](https://developers.google.com/google-ads/api/rest/design/overview.md.txt)
> - [JSON Field Mappings](https://developers.google.com/google-ads/api/rest/design/json-mappings.md.txt)
> - Consult the [REST API Reference](https://developers.google.com/google-ads/api/reference/rpc/latest/overview) for the specific service and method.

<br />

## Download an invoice PDF

Any invoice can be downloaded as a PDF file. Once you have
[retrieved](https://developers.google.com/google-ads/api/docs/billing/invoice.md.txt#retrieve-invoices) the [`Invoice`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.md.txt), you
need to send an HTTP request for the URL that is stored in its
[`pdf_url`](https://developers.google.com/google-ads/api/reference/rpc/v26/Invoice.md.txt#pdf_url) field. This request must be
authenticated using the same Google Account used to retrieve the invoice; that
is, you need to specify an OAuth access token generated using the Google Account
in the `Authorization: Bearer` request header:

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

The result is an invoice PDF content stored in the file
`<var>FILENAME</var>.pdf`.

## Common error codes

| Scenario | Error Code |
|---|---|
| Missing or empty billing setup, issue year, or issue month. | `RequestError.REQUIRED_FIELD_MISSING` |
| Can't parse given billing setup, issue year, or issue month. | `FieldError.INVALID_VALUE` |
| Request is for invoices issued before January 1, 2019. | `InvoiceError.YEAR_MONTH_TOO_OLD` |
| Request is for a customer who doesn't receive invoices. | `InvoiceError.NOT_INVOICED_CUSTOMER` |
| User doesn't have permission to view invoices of the billing setup. | `AuthorizationError.ACTION_NOT_PERMITTED` |