Method: advertiserInvoices.list

  • This API endpoint retrieves a list of invoices for a specified issue month.

  • The API is functional only if the billing profile invoice level is set to either advertiser or campaign non-consolidated.

  • The request requires the profile ID and advertiser ID as path parameters and the issue month as a required query parameter.

  • The response body includes the list of invoices, a pagination token, and identifies the resource type.

  • Each invoice contains details such as ID, payment profile/account IDs, issue and due dates, service dates, currency, various amount breakdowns (subtotal, tax, total), purchase order number, type, and potentially links to related invoices and a PDF URL.

Retrieves a list of invoices for a particular issue month. The api only works if the billing profile invoice level is set to either advertiser or campaign non-consolidated invoice level.

HTTP request

GET https://dfareporting.googleapis.com/dfareporting/v4/userprofiles/{profileId}/advertisers/{advertiserId}/invoices

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
profileId

string (int64 format)

User profile ID associated with this request.
advertiserId

string (int64 format)

Advertiser ID of this invoice.

Query parameters

Parameters
maxResults

integer

Maximum number of results to return.
issueMonth

string

Month for which invoices are needed in the format YYYYMM. Required field
pageToken

string

Value of the

nextPageToken

from the previous result page.

Request body

The request body must be empty.

Response body

Invoice advertiserInvoices.list Response

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

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

string

Identifies what kind of resource this is. Value: the fixed string

"dfareporting#advertiserInvoicesListResponse"

.
nextPageToken

string

Pagination token to be used for the next list operation.
invoices[]

object (Invoice)

Invoice collection

Authorization scopes

Requires the following OAuth scope:

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

Invoice

Contains information about a single invoice

JSON representation 
{
  "id": string,
  "paymentsProfileId": string,
  "paymentsAccountId": string,
  "issueDate": string,
  "dueDate": string,
  "serviceStartDate": string,
  "serviceEndDate": string,
  "currencyCode": string,
  "subtotalAmountMicros": string,
  "totalTaxAmountMicros": string,
  "totalAmountMicros": string,
  "purchaseOrderNumber": string,
  "invoiceType": enum (InvoiceType),
  "correctedInvoiceId": string,
  "replacedInvoiceIds": [
    string
  ],
  "pdfUrl": string,
  "campaign_summaries": [
    {
      object (CampaignSummary)
    }
  ],
  "kind": string
}
Fields
id

string

ID of this 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

string

The date when the invoice was issued.
dueDate

string

The invoice due date.
serviceStartDate

string

The invoice service start date.
serviceEndDate

string

The invoice service end date.
currencyCode

string

Invoice currency code in ISO 4217 format.
subtotalAmountMicros

string (int64 format)

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

string (int64 format)

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

string (int64 format)

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

string

Purchase order number associated with the invoice.
invoiceType

enum (InvoiceType)

The type of invoice document.
correctedInvoiceId

string

The originally issued invoice that is being adjusted by this invoice, if applicable. May appear on invoice PDF as Reference invoice number.
replacedInvoiceIds[]

string

The originally issued invoice(s) that is being cancelled by this invoice, if applicable. May appear on invoice PDF as Replaced invoice numbers. Note: There may be multiple replaced invoices due to consolidation of multiple invoices into a single invoice.
pdfUrl

string

The URL to download a PDF copy of the invoice. Note that 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. The URL will only be usable for 7 days from when the api is called.
campaign_summaries[]

object (CampaignSummary)

The list of summarized campaign information associated with this invoice.
kind

string

Identifies what kind of resource this is. Value: the fixed string

"dfareporting#invoice"

.

InvoiceType

Enums
INVOICE_TYPE_UNSPECIFIED
INVOICE_TYPE_CREDIT
INVOICE_TYPE_INVOICE

CampaignSummary

Represents a summarized campaign information associated with this invoice.

JSON representation 
{
  "campaignId": string,
  "billingInvoiceCode": string,
  "preTaxAmountMicros": string,
  "taxAmountMicros": string,
  "totalAmountMicros": string
}
Fields
campaignId

string (int64 format)

Campaign ID.
billingInvoiceCode

string

Campaign billing invoice code.
preTaxAmountMicros

string (int64 format)

The pre-tax amount for this campaign, in micros of the invoice's currency.
taxAmountMicros

string (int64 format)

The tax amount for this campaign, in micros of the invoice's currency.
totalAmountMicros

string (int64 format)

The total amount of charges for this campaign, in micros of the invoice's currency.