Method: advertisers.invoices.list

Lists invoices posted for an advertiser in a given month.

Invoices generated by billing profiles with a "Partner" invoice level are not retrievable through this method.

HTTP request

GET https://displayvideo.googleapis.com/v3/advertisers/{advertiserId}/invoices

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
advertiserId

string (int64 format)

Required. The ID of the advertiser to list invoices for.

Query parameters

Parameters
issueMonth

string

The month to list the invoices for. If not set, the request will retrieve invoices for the previous month.

Must be in the format YYYYMM.
loiSapinInvoiceType

enum (LoiSapinInvoiceType)

Select type of invoice to retrieve for Loi Sapin advertisers.

Only applicable to Loi Sapin advertisers. Will be ignored otherwise.
pageSize

integer

Requested page size. Must be between 1 and 200. If unspecified will default to 100. Returns error code INVALID_ARGUMENT if an invalid value is specified.
pageToken

string

A token identifying a page of results the server should return. Typically, this is the value of nextPageToken returned from the previous call to invoices.list method. If not specified, the first page of results will be returned.

Request body

The request body must be empty.

Response body

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

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

object (Invoice)

The list of invoices.

This list will be absent if empty.
nextPageToken

string

A token to retrieve the next page of results. Pass this value in the pageToken field in the subsequent call to invoices.list method to retrieve the next page of results.

This token will be absent if there are no more invoices to return.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/display-video
  • https://www.googleapis.com/auth/display-video-mediaplanning

For more information, see the OAuth 2.0 Overview.

LoiSapinInvoiceType

Possible types of invoices for Loi Sapin advertisers.

Enums
LOI_SAPIN_INVOICE_TYPE_UNSPECIFIED Value is not specified.
LOI_SAPIN_INVOICE_TYPE_MEDIA Invoices with Media cost.
LOI_SAPIN_INVOICE_TYPE_PLATFORM Invoices with Platform fee.

Invoice

A single invoice.

JSON representation 
{
  "name": string,
  "invoiceId": string,
  "displayName": string,
  "paymentsProfileId": string,
  "paymentsAccountId": string,
  "issueDate": {
    object (Date)
  },
  "dueDate": {
    object (Date)
  },
  "serviceDateRange": {
    object (DateRange)
  },
  "currencyCode": string,
  "subtotalAmountMicros": string,
  "totalTaxAmountMicros": string,
  "totalAmountMicros": string,
  "purchaseOrderNumber": string,
  "budgetInvoiceGroupingId": string,
  "invoiceType": enum (InvoiceType),
  "correctedInvoiceId": string,
  "replacedInvoiceIds": [
    string
  ],
  "pdfUrl": string,
  "budgetSummaries": [
    {
      object (BudgetSummary)
    }
  ],
  "nonBudgetMicros": string
}
Fields
name

string

The resource name of the invoice.
invoiceId

string

The unique ID of the invoice.
displayName

string

The display name of the invoice.
paymentsProfileId

string

The ID of the payments profile the invoice belongs to.

Appears on the invoice PDF as Billing ID.
paymentsAccountId

string

The ID of the payments account the invoice belongs to.

Appears on the invoice PDF as Billing Account Number.
issueDate

object (Date)

The date when the invoice was issued.
dueDate

object (Date)

The date when the invoice is due.
serviceDateRange

object (DateRange)

The service start and end dates which are covered by this invoice.
currencyCode

string

The currency used in the invoice in ISO 4217 format.
subtotalAmountMicros

string (int64 format)

The pre-tax subtotal amount, in micros of the invoice's currency.

For example, if currencyCode is USD, then 1000000 represents one US dollar.
totalTaxAmountMicros

string (int64 format)

The sum of all taxes in invoice, in micros of the invoice's currency.

For example, if currencyCode is USD, then 1000000 represents one US dollar.
totalAmountMicros

string (int64 format)

The invoice total amount, in micros of the invoice's currency.

For example, if currencyCode is USD, then 1000000 represents one US dollar.
purchaseOrderNumber

string

Purchase order number associated with the invoice.
budgetInvoiceGroupingId

string

The budget grouping ID for this invoice.

This field will only be set if the invoice level of the corresponding billing profile was set to "Budget invoice grouping ID".
invoiceType

enum (InvoiceType)

The type of invoice document.
correctedInvoiceId

string

The ID of the original invoice being adjusted by this invoice, if applicable.

May appear on the invoice PDF as Reference invoice number.

If replacedInvoiceIds is set, this field will be empty.
replacedInvoiceIds[]

string

The ID(s) of any originally issued invoice that is being cancelled by this invoice, if applicable. Multiple invoices may be listed if those invoices are being consolidated into a single invoice.

May appear on invoice PDF as Replaced invoice numbers.

If correctedInvoiceId is set, this field will be empty.
pdfUrl

string

The URL to download a PDF copy of the invoice.

This URL is user specific and requires a valid OAuth 2.0 access token to access. The access token must be provided in an Authorization: Bearer HTTP header and be authorized for one of the following scopes:

  • https://www.googleapis.com/auth/display-video-mediaplanning
  • https://www.googleapis.com/auth/display-video

The URL will be valid for 7 days after retrieval of this invoice object or until this invoice is retrieved again.
budgetSummaries[]

object (BudgetSummary)

The list of summarized information for each budget associated with this invoice.

This field will only be set if the invoice detail level of the corresponding billing profile was set to "Budget level PO".
nonBudgetMicros

string (int64 format)

The total amount of costs or adjustments not tied to a particular budget, in micros of the invoice's currency.

For example, if currencyCode is USD, then 1000000 represents one US dollar.

InvoiceType

Possible types of invoices.

Enums
INVOICE_TYPE_UNSPECIFIED Not specified or is unknown in this version.
INVOICE_TYPE_CREDIT The invoice has a negative amount.
INVOICE_TYPE_INVOICE The invoice has a positive amount.

BudgetSummary

Summarized information of an individual campaign budget.

JSON representation 
{
  "externalBudgetId": string,
  "prismaCpeCode": {
    object (PrismaCpeCode)
  },
  "preTaxAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string
}
Fields
externalBudgetId

string

Corresponds to the externalBudgetId of a campaign budget. If the value is not set in the campaign budget, this field will be empty.
prismaCpeCode

object (PrismaCpeCode)

Relevant client, product, and estimate codes from the Mediaocean Prisma tool.

Only applicable for campaign budgets with an externalBudgetSource of EXTERNAL_BUDGET_SOURCE_MEDIA_OCEAN.
preTaxAmountMicros

string (int64 format)

The sum of charges made under this budget before taxes, in micros of the invoice's currency.

For example, if currencyCode is USD, then 1000000 represents one US dollar.
taxAmountMicros

string (int64 format)

The amount of tax applied to charges under this budget, in micros of the invoice's currency.

For example, if currencyCode is USD, then 1000000 represents one US dollar.
totalAmountMicros

string (int64 format)

The total sum of charges made under this budget, including tax, in micros of the invoice's currency.

For example, if currencyCode is USD, then 1000000 represents one US dollar.