Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Method: customers.invoices.list

Returns all invoices associated with a billing setup, for a given month.

List of thrown errors: AuthenticationError AuthorizationError FieldError HeaderError InternalError InvoiceError QuotaError RequestError

HTTP request

GET https://googleads.googleapis.com/v12/customers/{customerId}/invoices

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

Required. The ID of the customer to fetch invoices for.

Query parameters

Parameters
billingSetup

string

Required. The billing setup resource name of the requested invoices.

customers/{customerId}/billingSetups/{billing_setup_id}
issueYear

string

Required. The issue year to retrieve invoices, in yyyy format. Only invoices issued in 2019 or later can be retrieved.
issueMonth

enum (MonthOfYear)

Required. The issue month to retrieve invoices.

Request body

The request body must be empty.

Response body

If successful, the response body contains data with the following structure:

Response message for InvoiceService.ListInvoices.

JSON representation 
{
  "invoices": [
    {
      object (Invoice)
    }
  ]
}
Fields
invoices[]

object (Invoice)

The list of invoices that match the billing setup and time period.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/adwords

For more information, see the OAuth 2.0 Overview.

Invoice

An invoice. All invoice information is snapshotted to match the PDF invoice. For invoices older than the launch of InvoiceService, the snapshotted information may not match the PDF invoice.

JSON representation 
{
  "resourceName": string,
  "type": enum (InvoiceType),
  "serviceDateRange": {
    object (DateRange)
  },
  "adjustmentsSubtotalAmountMicros": string,
  "adjustmentsTaxAmountMicros": string,
  "adjustmentsTotalAmountMicros": string,
  "regulatoryCostsSubtotalAmountMicros": string,
  "regulatoryCostsTaxAmountMicros": string,
  "regulatoryCostsTotalAmountMicros": string,
  "replacedInvoices": [
    string
  ],
  "accountBudgetSummaries": [
    {
      object (AccountBudgetSummary)
    }
  ],
  "accountSummaries": [
    {
      object (AccountSummary)
    }
  ],
  "id": string,
  "billingSetup": string,
  "paymentsAccountId": string,
  "paymentsProfileId": string,
  "issueDate": string,
  "dueDate": string,
  "currencyCode": string,
  "subtotalAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string,
  "correctedInvoice": string,
  "pdfUrl": string
}
Fields
resourceName

string

Output only. The resource name of the invoice. Multiple customers can share a given invoice, so multiple resource names may point to the same invoice. Invoice resource names have the form:

customers/{customerId}/invoices/{invoice_id}
type

enum (InvoiceType)

Output only. The type of invoice.
serviceDateRange

object (DateRange)

Output only. The service period date range of this invoice. The end date is inclusive.
adjustmentsSubtotalAmountMicros

string (int64 format)

Output only. The pretax subtotal amount of invoice level adjustments, in micros.
adjustmentsTaxAmountMicros

string (int64 format)

Output only. The sum of taxes on the invoice level adjustments, in micros.
adjustmentsTotalAmountMicros

string (int64 format)

Output only. The total amount of invoice level adjustments, in micros.
regulatoryCostsSubtotalAmountMicros

string (int64 format)

Output only. The pretax subtotal amount of invoice level regulatory costs, in micros.
regulatoryCostsTaxAmountMicros

string (int64 format)

Output only. The sum of taxes on the invoice level regulatory costs, in micros.
regulatoryCostsTotalAmountMicros

string (int64 format)

Output only. The total amount of invoice level regulatory costs, in micros.
replacedInvoices[]

string

Output only. The resource name of the original invoice(s) being rebilled or replaced by this invoice, if applicable. There might be multiple replaced invoices due to invoice consolidation. The replaced invoices may not belong to the same payments account. If replacedInvoices is set, correctedInvoice will not be set. Invoice resource names have the form:

customers/{customerId}/invoices/{invoice_id}
accountBudgetSummaries[]

object (AccountBudgetSummary)

Output only. The list of summarized account budget information associated with this invoice.
accountSummaries[]

object (AccountSummary)

Output only. The list of summarized account information associated with this invoice.
id

string

Output only. The ID of the invoice. It appears on the invoice PDF as "Invoice number".
billingSetup

string

Output only. The resource name of this invoice's billing setup.

customers/{customerId}/billingSetups/{billing_setup_id}
paymentsAccountId

string

Output only. A 16 digit ID used to identify the payments account associated with the billing setup, for example, "1234-5678-9012-3456". It appears on the invoice PDF as "Billing Account Number".
paymentsProfileId

string

Output only. A 12 digit ID used to identify the payments profile associated with the billing setup, for example, "1234-5678-9012". It appears on the invoice PDF as "Billing ID".
issueDate

string

Output only. The issue date in yyyy-mm-dd format. It appears on the invoice PDF as either "Issue date" or "Invoice date".
dueDate

string

Output only. The due date in yyyy-mm-dd format.
currencyCode

string

Output only. The currency code. All costs are returned in this currency. A subset of the currency codes derived from the ISO 4217 standard is supported.
subtotalAmountMicros

string (int64 format)

Output only. The pretax subtotal amount, in micros. This equals the sum of the AccountBudgetSummary subtotal amounts, Invoice.adjustments_subtotal_amount_micros, and Invoice.regulatory_costs_subtotal_amount_micros. Starting with v6, the Invoice.regulatory_costs_subtotal_amount_micros is no longer included.
taxAmountMicros

string (int64 format)

Output only. The sum of all taxes on the invoice, in micros. This equals the sum of the AccountBudgetSummary tax amounts, plus taxes not associated with a specific account budget.
totalAmountMicros

string (int64 format)

Output only. The total amount, in micros. This equals the sum of Invoice.subtotal_amount_micros and Invoice.tax_amount_micros. Starting with v6, Invoice.regulatory_costs_subtotal_amount_micros is also added as it is no longer already included in Invoice.tax_amount_micros.
correctedInvoice

string

Output only. The resource name of the original invoice corrected, wrote off, or canceled by this invoice, if applicable. If correctedInvoice is set, replacedInvoices will not be set. Invoice resource names have the form:

customers/{customerId}/invoices/{invoice_id}
pdfUrl

string

Output only. The URL to a PDF copy of the invoice. Users need to pass in their OAuth token to request the PDF with this URL.

InvoiceType

The possible type of invoices.

Enums
UNSPECIFIED Not specified.
UNKNOWN Used for return value only. Represents value unknown in this version.
CREDIT_MEMO An invoice with a negative amount. The account receives a credit.
INVOICE An invoice with a positive amount. The account owes a balance.

AccountBudgetSummary

Represents a summarized account budget billable cost.

JSON representation 
{
  "billableActivityDateRange": {
    object (DateRange)
  },
  "customer": string,
  "customerDescriptiveName": string,
  "accountBudget": string,
  "accountBudgetName": string,
  "purchaseOrderNumber": string,
  "subtotalAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string,
  "servedAmountMicros": string,
  "billedAmountMicros": string,
  "overdeliveryAmountMicros": string,
  "invalidActivityAmountMicros": string
}
Fields
billableActivityDateRange

object (DateRange)

Output only. The billable activity date range of the account budget, within the service date range of this invoice. The end date is inclusive. This can be different from the account budget's start and end time.
customer

string

Output only. The resource name of the customer associated with this account budget. This contains the customer ID, which appears on the invoice PDF as "Account ID". Customer resource names have the form:

customers/{customerId}
customerDescriptiveName

string

Output only. The descriptive name of the account budget's customer. It appears on the invoice PDF as "Account".
accountBudget

string

Output only. The resource name of the account budget associated with this summarized billable cost. AccountBudget resource names have the form:

customers/{customerId}/accountBudgets/{account_budget_id}
accountBudgetName

string

Output only. The name of the account budget. It appears on the invoice PDF as "Account budget".
purchaseOrderNumber

string

Output only. The purchase order number of the account budget. It appears on the invoice PDF as "Purchase order".
subtotalAmountMicros

string (int64 format)

Output only. The pretax subtotal amount attributable to this budget during the service period, in micros.
taxAmountMicros

string (int64 format)

Output only. The tax amount attributable to this budget during the service period, in micros.
totalAmountMicros

string (int64 format)

Output only. The total amount attributable to this budget during the service period, in micros. This equals the sum of the account budget subtotal amount and the account budget tax amount.
servedAmountMicros

string (int64 format)

Output only. Accessible only to customers on the allow-list. The pretax served amount attributable to this budget during the service period, in micros. This is only useful to reconcile invoice and delivery data.
billedAmountMicros

string (int64 format)

Output only. Accessible only to customers on the allow-list. The pretax billed amount attributable to this budget during the service period, in micros. This does not account for any adjustments.
overdeliveryAmountMicros

string (int64 format)

Output only. Accessible only to customers on the allow-list. The pretax overdelivery amount attributable to this budget during the service period, in micros (negative value).
invalidActivityAmountMicros

string (int64 format)

Output only. Accessible only to customers on the allow-list. The pretax invalid activity amount attributable to this budget in previous months, in micros (negative value).

AccountSummary

Represents a summarized view at account level. AccountSummary fields are accessible only to customers on the allow-list.

JSON representation 
{
  "customer": string,
  "billingCorrectionSubtotalAmountMicros": string,
  "billingCorrectionTaxAmountMicros": string,
  "billingCorrectionTotalAmountMicros": string,
  "couponAdjustmentSubtotalAmountMicros": string,
  "couponAdjustmentTaxAmountMicros": string,
  "couponAdjustmentTotalAmountMicros": string,
  "excessCreditAdjustmentSubtotalAmountMicros": string,
  "excessCreditAdjustmentTaxAmountMicros": string,
  "excessCreditAdjustmentTotalAmountMicros": string,
  "regulatoryCostsSubtotalAmountMicros": string,
  "regulatoryCostsTaxAmountMicros": string,
  "regulatoryCostsTotalAmountMicros": string,
  "subtotalAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string
}
Fields
customer

string

Output only. The account associated with the account summary.
billingCorrectionSubtotalAmountMicros

string (int64 format)

Output only. Pretax billing correction subtotal amount, in micros.
billingCorrectionTaxAmountMicros

string (int64 format)

Output only. Tax on billing correction, in micros.
billingCorrectionTotalAmountMicros

string (int64 format)

Output only. Total billing correction amount, in micros.
couponAdjustmentSubtotalAmountMicros

string (int64 format)

Output only. Pretax coupon adjustment subtotal amount, in micros.
couponAdjustmentTaxAmountMicros

string (int64 format)

Output only. Tax on coupon adjustment, in micros.
couponAdjustmentTotalAmountMicros

string (int64 format)

Output only. Total coupon adjustment amount, in micros.
excessCreditAdjustmentSubtotalAmountMicros

string (int64 format)

Output only. Pretax excess credit adjustment subtotal amount, in micros.
excessCreditAdjustmentTaxAmountMicros

string (int64 format)

Output only. Tax on excess credit adjustment, in micros.
excessCreditAdjustmentTotalAmountMicros

string (int64 format)

Output only. Total excess credit adjustment amount, in micros.
regulatoryCostsSubtotalAmountMicros

string (int64 format)

Output only. Pretax regulatory costs subtotal amount, in micros.
regulatoryCostsTaxAmountMicros

string (int64 format)

Output only. Tax on regulatory costs, in micros.
regulatoryCostsTotalAmountMicros

string (int64 format)

Output only. Total regulatory costs amount, in micros.
subtotalAmountMicros

string (int64 format)

Output only. Total pretax subtotal amount attributable to the account during the service period, in micros.
taxAmountMicros

string (int64 format)

Output only. Total tax amount attributable to the account during the service period, in micros.
totalAmountMicros

string (int64 format)

Output only. Total amount attributable to the account during the service period, in micros. This equals the sum of the subtotalAmountMicros and taxAmountMicros.