Google Ads Customers.invoices API

openapi: 3.2.0
info:
  title: Google Ads Customers.invoices API
  description: Manage your Google Ads accounts, campaigns, and reports with this API.
  version: v25
  x-discovery-revision: '20260721'
  contact:
    name: Google
    url: https://developers.google.com/google-ads/api/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://googleads.googleapis.com
  description: Google Ads API production server
security:
- oauth2:
  - https://www.googleapis.com/auth/adwords
tags:
- name: customers.invoices
paths:
  /v25/customers/{customersId}/invoices:
    parameters:
    - name: upload_protocol
      in: query
      required: false
      schema:
        type: string
      description: Upload protocol for media (e.g. "raw", "multipart").
    - name: quotaUser
      in: query
      required: false
      schema:
        type: string
      description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
    - name: fields
      in: query
      required: false
      schema:
        type: string
      description: Selector specifying which fields to include in a partial response.
    - name: $.xgafv
      in: query
      required: false
      schema:
        type: string
        enum:
        - '1'
        - '2'
        x-enumDescriptions:
        - v1 error format
        - v2 error format
      description: V1 error format.
    - name: callback
      in: query
      required: false
      schema:
        type: string
      description: JSONP
    - name: prettyPrint
      in: query
      required: false
      schema:
        type: boolean
        default: 'true'
      description: Returns response with indentations and line breaks.
    - name: access_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth access token.
    - name: uploadType
      in: query
      required: false
      schema:
        type: string
      description: Legacy upload protocol for media (e.g. "media", "multipart").
    - name: key
      in: query
      required: false
      schema:
        type: string
      description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
    - name: oauth_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth 2.0 token for the current user.
    - name: alt
      in: query
      required: false
      schema:
        x-enumDescriptions:
        - Responses with Content-Type of application/json
        - Media download with context-dependent Content-Type
        - Responses with Content-Type of application/x-protobuf
        type: string
        default: json
        enum:
        - json
        - media
        - proto
      description: Data format for response.
    get:
      operationId: googleads_customers_invoices_list
      summary: Returns all invoices associated with a billing setup, for a given month
      tags:
      - customers.invoices
      description: 'Returns all invoices associated with a billing setup, for a given month. List of thrown errors: [AuthenticationError]() [AuthorizationError]() [FieldError]() [HeaderError]() [InternalError]() [InvoiceError]() [QuotaError]() [RequestError]()'
      parameters:
      - name: billingSetup
        in: query
        required: false
        schema:
          type: string
        description: Required. The billing setup resource name of the requested invoices. `customers/{customer_id}/billingSetups/{billing_setup_id}`
      - name: issueMonth
        in: query
        required: false
        schema:
          type: string
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - JANUARY
          - FEBRUARY
          - MARCH
          - APRIL
          - MAY
          - JUNE
          - JULY
          - AUGUST
          - SEPTEMBER
          - OCTOBER
          - NOVEMBER
          - DECEMBER
          x-enumDescriptions:
          - Not specified.
          - The value is unknown in this version.
          - January.
          - February.
          - March.
          - April.
          - May.
          - June.
          - July.
          - August.
          - September.
          - October.
          - November.
          - December.
        description: Required. The issue month to retrieve invoices.
      - name: issueYear
        in: query
        required: false
        schema:
          type: string
        description: Required. The issue year to retrieve invoices, in yyyy format. Only invoices issued in 2019 or later can be retrieved.
      - name: customerId
        in: path
        required: true
        schema:
          pattern: ^[^/]+$
          type: string
        description: Required. The ID of the customer to fetch invoices for.
      - name: includeGranularLevelInvoiceDetails
        in: query
        required: false
        schema:
          type: boolean
        description: Optional. When true, the response will include more granular level invoice details such as campaign level cost breakdown, itemized regulatory costs and adjustments. The default value is false.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__ListInvoicesResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Resources__Invoice:
      type: object
      properties:
        exportChargeTaxAmountMicros:
          format: int64
          type: string
          description: Output only. The sum of taxes on the invoice level export charges, in micros.
        paymentsAccountId:
          description: 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".
          type: string
        totalAmountMicros:
          description: 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).
          type: string
          format: int64
        subtotalAmountMicros:
          type: string
          description: 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.
          format: int64
        serviceDateRange:
          description: Output only. The service period date range of this invoice. The end date is inclusive.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__DateRange'
        taxAmountMicros:
          format: int64
          description: 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.
          type: string
        dueDate:
          description: Output only. The due date in yyyy-mm-dd format.
          type: string
        billingSetup:
          type: string
          description: Output only. The resource name of this invoice's billing setup. `customers/{customer_id}/billingSetups/{billing_setup_id}`
        adjustmentsTotalAmountMicros:
          format: int64
          type: string
          description: Output only. The total amount of invoice level adjustments, in micros.
        regulatoryCostsTaxAmountMicros:
          format: int64
          type: string
          description: Output only. The sum of taxes on the invoice level regulatory costs, in micros.
        accountBudgetSummaries:
          type: array
          description: Output only. The list of summarized account budget information associated with this invoice.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources_Invoice_AccountBudgetSummary'
        paymentsProfileId:
          type: string
          description: 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".
        regulatoryCostsSubtotalAmountMicros:
          description: Output only. The pretax subtotal amount of invoice level regulatory costs, in micros.
          type: string
          format: int64
        type:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - An invoice with a negative amount. The account receives a credit.
          - An invoice with a positive amount. The account owes a balance.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - CREDIT_MEMO
          - INVOICE
          type: string
          description: Output only. The type of invoice.
        adjustmentsSubtotalAmountMicros:
          description: Output only. The pretax subtotal amount of invoice level adjustments, in micros.
          type: string
          format: int64
        pdfUrl:
          type: string
          description: 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.
        currencyCode:
          description: 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.
          type: string
        accountSummaries:
          type: array
          description: Output only. The list of summarized account information associated with this invoice.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources_Invoice_AccountSummary'
        correctedInvoice:
          description: 'Output only. The resource name of the original invoice corrected, wrote off, or canceled by this invoice, if applicable. If `corrected_invoice` is set, `replaced_invoices` will not be set. Invoice resource names have the form: `customers/{customer_id}/invoices/{invoice_id}`'
          type: string
        replacedInvoices:
          description: '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 `replaced_invoices` is set, `corrected_invoice` will not be set. Invoice resource names have the form: `customers/{customer_id}/invoices/{invoice_id}`'
          items:
            type: string
          type: array
        adjustmentsTaxAmountMicros:
          type: string
          description: Output only. The sum of taxes on the invoice level adjustments, in micros.
          format: int64
        exportChargeTotalAmountMicros:
          format: int64
          description: Output only. The total amount of invoice level export charges, in micros.
          type: string
        id:
          description: Output only. The ID of the invoice. It appears on the invoice PDF as "Invoice number".
          type: string
        issueDate:
          description: Output only. The issue date in yyyy-mm-dd format. It appears on the invoice PDF as either "Issue date" or "Invoice date".
          type: string
        resourceName:
          description: '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/{customer_id}/invoices/{invoice_id}`'
          type: string
        regulatoryCostsTotalAmountMicros:
          description: Output only. The total amount of invoice level regulatory costs, in micros.
          type: string
          format: int64
        exportChargeSubtotalAmountMicros:
          format: int64
          description: Output only. The pretax subtotal amount of invoice level export charges, in micros.
          type: string
      description: 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.
    GoogleAdsGoogleadsV25Resources_Invoice_AdjustmentSummary:
      type: object
      properties:
        adjustmentDescription:
          description: 'Output only. The description of the adjustment. Example: Incentive Adjustment, discount.'
          type: string
        amountMicros:
          description: Output only. The amount of the adjustment, in micros. The currency code for this amount is the same as the Invoice.currency_code.
          type: string
          format: int64
      description: Represents adjustment information associated with an account.
    GoogleAdsGoogleadsV25Services__ListInvoicesResponse:
      type: object
      properties:
        invoices:
          description: The list of invoices that match the billing setup and time period.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__Invoice'
          type: array
      description: Response message for InvoiceService.ListInvoices.
    GoogleAdsGoogleadsV25Resources_Invoice_CampaignSummary:
      type: object
      properties:
        amountMicros:
          type: string
          description: Output only. The amount attributable to this campaign for the given unit of measure during the service period, in micros. The currency code for this amount is the same as the Invoice.currency_code.
          format: int64
        campaignDescription:
          type: string
          description: Output only. The description of the campaign. This is generally the same as the campaign name, but may differ.
        unitOfMeasure:
          type: string
          description: Output only. The unit of measure for the quantity served.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - CLICKS
          - IMPRESSIONS
          - ACQUISITIONS
          - PHONE_CALLS
          - VIDEO_PLAYS
          - DAYS
          - AUDIO_PLAYS
          - ENGAGEMENTS
          - SECONDS
          - LEADS
          - GUEST_STAYS
          - HOURS
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Clicks as unit of measure.
          - Impressions as unit of measure.
          - Acquisitions as unit of measure.
          - Phone calls as unit of measure.
          - Video plays as unit of measure.
          - Days as unit of measure.
          - Audio plays as unit of measure.
          - Engagements as unit of measure.
          - Seconds as unit of measure.
          - Leads as unit of measure.
          - Guest stays as unit of measure.
          - Hours as unit of measure.
        quantity:
          format: int64
          description: Output only. The quantity served for the given unit of measure.
          type: string
      description: Represents campaign level billable cost information associated with an account budget.
    GoogleAdsGoogleadsV25Resources_Invoice_RegulatoryCostSummary:
      description: Represents regulatory cost information associated with an account.
      type: object
      properties:
        regulatoryFeeType:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Represents Austria DST fee.
          - Represents Türkiye regulatory operating cost.
          - Represents UK DST fee.
          - Represents Spain regulatory operating cost.
          - Represents France regulatory operating cost.
          - Represents Italy regulatory operating cost.
          - Represents India regulatory operating cost.
          - Represents Poland regulatory operating cost.
          - Represents operating charges.
          - Represents Canada DST fee.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - AUSTRIA_DST_FEE
          - TURKIYE_REGULATORY_OPERATING_COST
          - UK_DST_FEE
          - SPAIN_REGULATORY_OPERATING_COST
          - FRANCE_REGULATORY_OPERATING_COST
          - ITALY_REGULATORY_OPERATING_COST
          - INDIA_REGULATORY_OPERATING_COST
          - POLAND_REGULATORY_OPERATING_COST
          - OPERATING_CHARGES
          - CANADA_DST_FEE
          description: Output only. The type of regulatory fee.
          type: string
        amountMicros:
          format: int64
          type: string
          description: Output only. The amount of the regulatory fee, in micros. The currency code for this amount is the same as the Invoice.currency_code.
    GoogleAdsGoogleadsV25Common__DateRange:
      type: object
      properties:
        startDate:
          type: string
          description: The start date, in yyyy-mm-dd format. This date is inclusive.
        endDate:
          description: The end date, in yyyy-mm-dd format. This date is inclusive.
          type: string
      description: A date range.
    GoogleAdsGoogleadsV25Resources_Invoice_AccountBudgetSummary:
      type: object
      properties:
        invalidActivitySummaries:
          type: array
          description: Output only. The list of summarized invalid activity credits with original linkages.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources_Invoice_InvalidActivitySummary'
        servedAmountMicros:
          type: string
          description: 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.
          format: int64
        campaignSummaries:
          type: array
          description: Output only. The list of summarized campaign level information associated with this account budget.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources_Invoice_CampaignSummary'
        billedAmountMicros:
          format: int64
          description: Output only. The pretax billed amount attributable to this budget during the service period, in micros. This does not account for any adjustments.
          type: string
        customerDescriptiveName:
          description: Output only. The descriptive name of the account budget's customer. It appears on the invoice PDF as "Account".
          type: string
        invalidActivityAmountMicros:
          format: int64
          type: string
          description: Output only. The pretax invalid activity amount attributable to this budget in previous months, in micros (negative value).
        customer:
          description: '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/{customer_id}`'
          type: string
        totalAmountMicros:
          format: int64
          description: 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.
          type: string
        accountBudget:
          description: 'Output only. The resource name of the account budget associated with this summarized billable cost. AccountBudget resource names have the form: `customers/{customer_id}/accountBudgets/{account_budget_id}`'
          type: string
        overdeliveryAmountMicros:
          description: Output only. The pretax overdelivery amount attributable to this budget during the service period, in micros (negative value).
          type: string
          format: int64
        subtotalAmountMicros:
          format: int64
          description: Output only. The pretax subtotal amount attributable to this budget during the service period, in micros.
          type: string
        billableActivityDateRange:
          description: 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.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__DateRange'
        taxAmountMicros:
          description: Output only. The tax amount attributable to this budget during the service period, in micros.
          type: string
          format: int64
        accountBudgetName:
          type: string
          description: Output only. The name of the account budget. It appears on the invoice PDF as "Account budget".
        purchaseOrderNumber:
          type: string
          description: Output only. The purchase order number of the account budget. It appears on the invoice PDF as "Purchase order".
      description: Represents a summarized account budget billable cost.
    GoogleAdsGoogleadsV25Resources_Invoice_InvalidActivitySummary:
      type: object
      properties:
        originalMonthOfService:
          x-enumDescriptions:
          - Not specified.
          - The value is unknown in this version.
          - January.
          - February.
          - March.
          - April.
          - May.
          - June.
          - July.
          - August.
          - September.
          - October.
          - November.
          - December.
          description: Output only. Original month of service related to this invalid activity credit.
          type: string
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - JANUARY
          - FEBRUARY
          - MARCH
          - APRIL
          - MAY
          - JUNE
          - JULY
          - AUGUST
          - SEPTEMBER
          - OCTOBER
          - NOVEMBER
          - DECEMBER
        originalYearOfService:
          description: Output only. Original year of service related to this invalid activity credit.
          type: string
        originalAccountBudgetName:
          type: string
          description: Output only. Original account budget name related to this invalid activity credit.
        originalInvoiceId:
          description: Output only. Original invoice number related to this invalid activity credit.
          type: string
        amountMicros:
          description: Output only. Invalid activity amount in micros.
          type: string
          format: int64
        originalPurchaseOrderNumber:
          description: Output only. Original purchase order number related to this invalid activity credit.
          type: string
      description: Details about the invalid activity for the invoice that contain additional details about invoice against which corrections are made.
    GoogleAdsGoogleadsV25Resources_Invoice_AccountSummary:
      description: Represents a summarized view at account level.
      type: object
      properties:
        excessCreditAdjustmentTaxAmountMicros:
          format: int64
          type: string
          description: Output only. Tax on excess credit adjustment, in micros.
        couponAdjustmentTotalAmountMicros:
          format: int64
          description: Output only. Total coupon adjustment amount, in micros.
          type: string
        exportChargeTotalAmountMicros:
          format: int64
          type: string
          description: Output only. Total export charge amount, in micros.
        billingCorrectionSubtotalAmountMicros:
          format: int64
          description: Output only. Pretax billing correction subtotal amount, in micros.
          type: string
        regulatoryCostsTaxAmountMicros:
          format: int64
          type: string
          description: Output only. Tax on regulatory costs, in micros.
        excessCreditAdjustmentTotalAmountMicros:
          format: int64
          description: Output only. Total excess credit adjustment amount, in micros.
          type: string
        regulatoryCostsSubtotalAmountMicros:
          format: int64
          type: string
          description: Output only. Pretax regulatory costs subtotal amount, in micros.
        regulatoryCostsTotalAmountMicros:
          format: int64
          description: Output only. Total regulatory costs amount, in micros.
          type: string
        adjustmentSummaries:
          type: array
          description: Output only. The list of adjustment information associated with this account.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources_Invoice_AdjustmentSummary'
        billingCorrectionTotalAmountMicros:
          format: int64
          description: Output only. Total billing correction amount, in micros.
          type: string
        exportChargeSubtotalAmountMicros:
          format: int64
          type: string
          description: Output only. Pretax export charge subtotal amount, in micros.
        exportChargeTaxAmountMicros:
          type: string
          description: Output only. Tax on export charge, in micros.
          format: int64
        regulatoryCostSummaries:
          description: Output only. The list of regulatory cost information associated with this account.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources_Invoice_RegulatoryCostSummary'
          type: array
        customer:
          description: Output only. The account associated with the account summary.
          type: string
        totalAmountMicros:
          format: int64
          type: string
          description: Output only. Total amount attributable to the account during the service period, in micros. This equals the sum of the subtotal_amount_micros and tax_amount_micros.
        billingCorrectionTaxAmountMicros:
          type: string
          description: Output only. Tax on billing correction, in micros.
          format: int64
        excessCreditAdjustmentSubtotalAmountMicros:
          format: int64
          type: string
          description: Output only. Pretax excess credit adjustment subtotal amount, in micros.
        subtotalAmountMicros:
          format: int64
          type: string
          description: Output only. Total pretax subtotal amount attributable to the account during the service period, in micros.
        taxAmountMicros:
          format: int64
          description: Output only. Total tax amount attributable to the account during the service period, in micros.
          type: string
        couponAdjustmentSubtotalAmountMicros:
          description: Output only. Pretax coupon adjustment subtotal amount, in micros.
          type: string
          format: int64
        couponAdjustmentTaxAmountMicros:
          description: Output only. Tax on coupon adjustment, in micros.
          type: string
          format: int64
  securitySchemes:
    oauth2:
      type: oauth2
      description: Google OAuth 2.0. Google Ads API additionally requires a developer token in the developer-token header.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/adwords: See, edit, create, and delete your Google Ads accounts and data.
externalDocs:
  url: https://developers.google.com/google-ads/api/
x-source: https://googleads.googleapis.com/$discovery/rest?version=v25
x-generated-by: API Evangelist enrichment pipeline — mechanical conversion of the first-party Google API Discovery Document