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/v17/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

Response message for InvoiceService.ListInvoices.

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

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,
  "exportChargeSubtotalAmountMicros": string,
  "exportChargeTaxAmountMicros": string,
  "exportChargeTotalAmountMicros": 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.
exportChargeSubtotalAmountMicros

string (int64 format)

Output only. The pretax subtotal amount of invoice level export charges, in micros.
exportChargeTaxAmountMicros

string (int64 format)

Output only. The sum of taxes on the invoice level export charges, in micros.
exportChargeTotalAmountMicros

string (int64 format)

Output only. The total amount of invoice level export charges, in micros.
subtotalAmountMicros

string (int64 format)

Output only. The pretax subtotal amount, in micros. This is equal to the sum of the AccountBudgetSummary subtotal amounts and Invoice.adjustments_subtotal_amount_micros.
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, Invoice.tax_amount_micros, Invoice.regulatory_costs_subtotal_amount_micros, and Invoice.export_charge_subtotal_amount_micros (which is separated into a separate line item starting with V14.1).
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)
  },
  "invalidActivitySummaries": [
    {
      object (InvalidActivitySummary)
    }
  ],
  "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.
invalidActivitySummaries[]

object (InvalidActivitySummary)

Output only. The list of summarized invalid activity credits with original linkages.
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. 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. 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. The pretax overdelivery amount attributable to this budget during the service period, in micros (negative value).
invalidActivityAmountMicros

string (int64 format)

Output only. The pretax invalid activity amount attributable to this budget in previous months, in micros (negative value).

InvalidActivitySummary

Details about the invalid activity for the invoice that contain additional details about invoice against which corrections are made.

JSON representation 
{
  "originalMonthOfService": enum (MonthOfYear),
  "originalYearOfService": string,
  "originalInvoiceId": string,
  "originalAccountBudgetName": string,
  "originalPurchaseOrderNumber": string,
  "amountMicros": string
}
Fields
originalMonthOfService

enum (MonthOfYear)

Output only. Original month of service related to this invalid activity credit.
originalYearOfService

string

Output only. Original year of service related to this invalid activity credit.
originalInvoiceId

string

Output only. Original invoice number related to this invalid activity credit.
originalAccountBudgetName

string

Output only. Original account budget name related to this invalid activity credit.
originalPurchaseOrderNumber

string

Output only. Original purchase order number related to this invalid activity credit.
amountMicros

string (int64 format)

Output only. Invalid activity amount in micros.

AccountSummary

Represents a summarized view at account level.

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,
  "exportChargeSubtotalAmountMicros": string,
  "exportChargeTaxAmountMicros": string,
  "exportChargeTotalAmountMicros": 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.
exportChargeSubtotalAmountMicros

string (int64 format)

Output only. Pretax export charge subtotal amount, in micros.
exportChargeTaxAmountMicros

string (int64 format)

Output only. Tax on export charge, in micros.
exportChargeTotalAmountMicros

string (int64 format)

Output only. Total export charge 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.