Google Ads API is returning to beta status. Please read our blog post for more details.

Use the InvoiceService to retrieve invoices metadata for a given month of a Google Ads account that has opted in for monthly invoicing.

Prerequisites

Retrieving invoices

  1. Create a ListInvoicesRequest object and set the following required fields. A sample request is included below.
    • customer_id: the customer ID of the account you want to get its monthly invoice.
    • billing_setup: the billing setup of the account you wish to use for getting an invoice.
    • issue_year: the year for which you are requesting the invoice.
    • issue_month: the month for which you are requesting the invoice.
  2. Send the previously created ListInvoicesRequest object to InvoiceService.ListInvoices(). You can use cURL to make the API call.
  3. The response is a ListInvoicesResponse containing several Invoice objects with some fields populated (a sample response is included below). Some of the more important fields are:
    • account_budget_summaries: The list of summarized account budget information associated with this invoice. Each account budget information contains the following fields:
      • customer_id: the unique ID of the customer you're requesting the invoice for.
      • customer_descriptive_name: the descriptive name of the account budget's customer.
      • account_budget: the resource name of account budget.
      • account_budget_name: the name of the account budget.
      • purchase_order_number: the purchase order number of the account budget.
    • total_amount_micros
    • subtotal_amount_micros
    • tax_amount_micros
    • pdf_url: The URL to a PDF copy of the invoice.

Visit this reference page for all field descriptions.

Sample request

ListInvoicesRequest

customer_id = 111122223333
billing_setup = "customers/111122223333/billingSetups/123"
issue_year = "2019"
issue_month = JANUARY

Sample response

ListInvoicesResponse

{
  "invoices": [
    {
      resource_name: "customers/1234567890/invoices/333344445",
      id {
        value: "1111222233"
      },
      type: INVOICE,
      billing_setup {
        value: "customers/1234567890/billingSetups/1111222233"
      },
      payments_account_id {
        value: "1234-8888-9999-0000"
      },
      payments_profile_id {
        value: "1234-5555-6666"
      },
      issue_date {
        value: "2019-07-29"
      },
      due_date {
        value: "2019-09-12"
      },
      service_date_range {
        start_date {
          value: "2019-07-28"
        },
        end_date {
          value: "2019-07-28"
        }
      },
      currency_code {
        value: "NZD"
      },
      invoice_level_adjustments_micros {
      },
      subtotal_amount_micros {
        value: 40000000
      },
      tax_amount_micros {
        value: 6000000
      },
      total_amount_micros {
        value: 46000000
      },
      pdf_url {
        value: "https://ads.google.com/payments/apis-secure/doc/trs?doc=sdfasdxcv"
      },
      account_budget_summaries: [
        {
          customer {
            value: "customers/7777000011"
          },
          customer_descriptive_name {
            value: "adsr39"
          },
          account_budget {
            value: "customers/7777000011/accountBudgets/24"
          },
          account_budget_name {
            value: "pastEndedBudget"
          },
          purchase_order_number {
            value: "PO number"
          },
          subtotal_amount_micros {
            value: 40000000
          },
          tax_amount_micros {
            value: 6000000
          },
          total_amount_micros {
            value: 46000000
          },
          billable_activity_date_range {
            start_date {
              value: "2019-07-28"
            },
            end_date {
              value: "2019-07-28"
            }
          }
        }
      ]
    },
    //...More Invoice objects
  ]
}

Retrieving a PDF invoice

Invoices can also be downloaded as a PDF file:

  1. Retrieve invoices for a given billing setup.
  2. Select one invoice you want to retrieve.
  3. Send an HTTP request for the URL stored in the pdf_url field of the Invoice object you selected using cURL. This request must be authenticated using the same Google account as in step 1; 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" \
         https://ads.google.com/payments/apis-secure/doc/trs?doc=sdfasdxcv > filename.pdf
    

    The response is then redirected to filename.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, issue month FieldError.INVALID_VALUE
Request is for invoices issued before 2019-01-01 InvoiceError.YEAR_MONTH_TOO_OLD
Request is on customer who doesn't receive invoices InvoiceError.NOT_INVOICED_CUSTOMER
User doesn't have permission to view invoice of the billing setup AuthorizationError.ACTION_NOT_PERMITTED