Invoice Service

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:

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"
      },
      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