Method: customers.invoices.list

返回指定月份内与结算设置关联的所有账单。

抛出的错误的列表：AuthenticationError AuthorizationError FieldError HeaderError InternalError InvoiceError QuotaError RequestError

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
customerId

string

必需。要获取其账单的客户 ID。

查询参数

参数
billingSetup

string

必需。所请求账单的结算设置资源名称。

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

string

必需。用于检索账单的开具年份，格式为 yyyy。只能检索 2019 年或之后发出的账单。
issueMonth

enum (MonthOfYear)

必需。检索账单的开具月份。

请求正文

请求正文必须为空。

响应正文

InvoiceService.ListInvoices 的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "invoices": [
    {
      object (Invoice)
    }
  ]
}
字段
invoices[]

object (Invoice)

与结算设置和时间段匹配的账单列表。

授权范围

需要以下 OAuth 范围：

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

如需了解详情，请参阅 OAuth 2.0 概览。

账单

账单。系统会截取所有账单信息的快照，以便与 PDF 账单保持一致。对于早于 InvoiceService 启用时间的帐单，快照的信息可能与 PDF 帐单不一致。

JSON 表示法 
{
  "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
}
字段
resourceName

string

仅限输出。账单的资源名称。多个客户可以共用同一账单，因此多个资源名称可能会指向同一账单。账单资源名称采用以下格式：

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

enum (InvoiceType)

仅限输出。账单类型。
serviceDateRange

object (DateRange)

仅限输出。此账单的服务期限日期范围。结束日期含在内。
adjustmentsSubtotalAmountMicros

string (int64 format)

仅限输出。账单级调整项的税前小计金额（以微单位表示）。
adjustmentsTaxAmountMicros

string (int64 format)

仅限输出。账单级调整项的税费总和（以微单位表示）。
adjustmentsTotalAmountMicros

string (int64 format)

仅限输出。账单级调整项的总金额，以微单位表示。
regulatoryCostsSubtotalAmountMicros

string (int64 format)

仅限输出。账单级监管费用的税前金额小计（以微单位表示）。
regulatoryCostsTaxAmountMicros

string (int64 format)

仅限输出。账单级监管费用的税费总和（以微单位表示）。
regulatoryCostsTotalAmountMicros

string (int64 format)

仅限输出。账单级监管费用的总金额，以微单位表示。
replacedInvoices[]

string

仅限输出。被此账单重新结算或替换的原始账单的资源名称（如果适用）。由于账单合并，可能会有多个被替换的账单。替换的账单可能不属于同一付款账号。如果设置了 replacedInvoices，则不会设置 correctedInvoice。账单资源名称采用以下格式：

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

object (AccountBudgetSummary)

仅限输出。与此账单关联的账号预算汇总信息列表。
accountSummaries[]

object (AccountSummary)

仅限输出。与此账单关联的账号汇总列表。
id

string

仅限输出。账单的 ID。此 ID 会以“账单编号”的形式显示在 PDF 账单上。
billingSetup

string

仅限输出。此账单结算设置的资源名称。

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

string

仅限输出。用于标识与结算设置相关联的付款帐号的 16 位数 ID，例如“1234-5678-9012-3456”。它在 PDF 帐单上显示为“结算账号”。
paymentsProfileId

string

仅限输出。用于标识与结算设置相关联的付款资料的 12 位数 ID，例如“1234-5678-9012”。在 PDF 帐单上，此 ID 会显示为“结算 ID”。
issueDate

string

仅限输出。开具日期，格式为 yyyy-mm-dd。它在账单 PDF 上显示为“开具日期”或“账单日期”。
dueDate

string

仅限输出。格式为 yyyy-mm-dd 的截止日期。
currencyCode

string

仅限输出。货币代码。所有费用均以该币种返回。支持派生自 ISO 4217 标准的部分货币代码。
exportChargeSubtotalAmountMicros

string (int64 format)

仅限输出。账单级出口费用的税前小计金额（以微单位表示）。
exportChargeTaxAmountMicros

string (int64 format)

仅限输出。账单级出口费用的税费总和（以微单位表示）。
exportChargeTotalAmountMicros

string (int64 format)

仅限输出。账单级出口费用的总金额，以微单位表示。
subtotalAmountMicros

string (int64 format)

仅限输出。税前金额小计（以微单位表示）。这等于 AccountBudgetSummary 小计金额和 Invoice.adjustments_subtotal_amount_micros 的总和。
taxAmountMicros

string (int64 format)

仅限输出。账单上所有税费的总和，以微单位表示。这等于 AccountBudgetSummary 税费金额总和，加上未与特定帐号预算关联的税费。
totalAmountMicros

string (int64 format)

仅限输出。总金额（以微单位表示）。此金额等于 Invoice.subtotal_amount_micros、Invoice.tax_amount_micros、Invoice.regulatory_costs_subtotal_amount_micros 和 Invoice.export_charge_subtotal_amount_micros（从 V14.1 开始单独的订单项）的总和。
correctedInvoice

string

仅限输出。由此账单更正、核销或取消的原始账单的资源名称（如果适用）。如果设置了 correctedInvoice，则不会设置 replacedInvoices。账单资源名称采用以下格式：

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

string

仅限输出。指向账单 PDF 副本的网址。用户需要传递其 OAuth 令牌才能请求使用此网址的 PDF。

InvoiceType

可能的账单类型。

枚举
UNSPECIFIED 未指定。
UNKNOWN 仅用于返回值。表示此版本中未知的值。
CREDIT_MEMO 金额为负的账单。相应帐号将获得一笔赠金。
INVOICE 金额为正数的账单。该帐号有未结余额。

AccountBudgetSummary

表示账号预算可结算费用的汇总。

JSON 表示法 
{
  "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
}
字段
billableActivityDateRange

object (DateRange)

仅限输出。账号预算的可结算活动日期范围，在此账单的服务日期范围内。结束日期含在内。此时间可以不同于账号预算的开始时间和结束时间。
invalidActivitySummaries[]

object (InvalidActivitySummary)

仅限输出。具有原始关联的无效活动返还金额汇总列表。
customer

string

仅限输出。与此账号预算关联的客户的资源名称。此文件包含客户 ID，在 PDF 格式的帐单上显示为“Account ID”（帐号 ID）。客户资源名称采用以下格式：

customers/{customerId}
customerDescriptiveName

string

仅限输出。帐号预算客户的描述性名称。此 ID 会以“帐号”的形式显示在 PDF 帐单上。
accountBudget

string

仅限输出。与此汇总的可结算费用相关联的账号预算的资源名称。AccountBudget 资源名称采用以下格式：

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

string

仅限输出。帐号预算的名称。它在 PDF 账单上会显示为“帐号预算”。
purchaseOrderNumber

string

仅限输出。帐号预算的采购订单编号。它在 PDF 账单上会显示为“采购订单”。
subtotalAmountMicros

string (int64 format)

仅限输出。服务期间属于此预算的税前小计金额（以微单位表示）。
taxAmountMicros

string (int64 format)

仅限输出。服务期内归因于此预算的税额（以微单位表示）。
totalAmountMicros

string (int64 format)

仅限输出。在服务期内归因于此预算的总金额（以微单位表示）。这等于账号预算小计金额和账号预算税费金额的总和。
servedAmountMicros

string (int64 format)

仅限输出。服务期间归因于此预算的税前服务金额（以微单位表示）。这仅用于对账单和投放数据进行对账。
billedAmountMicros

string (int64 format)

仅限输出。服务期间归因于此预算的税前结算金额（以微单位表示）。这未考虑任何调整。
overdeliveryAmountMicros

string (int64 format)

仅限输出。服务期间归因于此预算的税前超额投放金额，以微单位（负值）表示。
invalidActivityAmountMicros

string (int64 format)

仅限输出。归因于这笔预算在以往月份的税前无效活动金额，以微单位（负值）表示。

InvalidActivitySummary

账单中无效活动的详细信息，包含要更正的账单的其他详细信息。

JSON 表示法 
{
  "originalMonthOfService": enum (MonthOfYear),
  "originalYearOfService": string,
  "originalInvoiceId": string,
  "originalAccountBudgetName": string,
  "originalPurchaseOrderNumber": string,
  "amountMicros": string
}
字段
originalMonthOfService

enum (MonthOfYear)

仅限输出。与这笔无效活动返还金额相关的原始服务月份。
originalYearOfService

string

仅限输出。与此无效活动返还金额相关的原始服务年份。
originalInvoiceId

string

仅限输出。与此无效活动返还金额相关的原始账单编号。
originalAccountBudgetName

string

仅限输出。与此无效活动贷记项相关的原始账号预算名称。
originalPurchaseOrderNumber

string

仅限输出。与此无效活动返还金额有关的原始采购订单编号。
amountMicros

string (int64 format)

仅限输出。无效活动量（以微单位表示）。

AccountSummary

表示帐号级汇总视图。

JSON 表示法 
{
  "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
}
字段
customer

string

仅限输出。与账号摘要相关联的账号。
billingCorrectionSubtotalAmountMicros

string (int64 format)

仅限输出。税前结算更正小计金额（以微单位表示）。
billingCorrectionTaxAmountMicros

string (int64 format)

仅限输出。账单更正税费（以微单位表示）。
billingCorrectionTotalAmountMicros

string (int64 format)

仅限输出。总账单修正金额（以微单位表示）。
couponAdjustmentSubtotalAmountMicros

string (int64 format)

仅限输出。税前优惠券调整金额小计金额，以微单位表示。
couponAdjustmentTaxAmountMicros

string (int64 format)

仅限输出。优惠券调整税费，以微单位表示。
couponAdjustmentTotalAmountMicros

string (int64 format)

仅限输出。优惠券总调整金额（以微单位表示）。
excessCreditAdjustmentSubtotalAmountMicros

string (int64 format)

仅限输出。税前超额贷记调整项小计金额（以微单位表示）。
excessCreditAdjustmentTaxAmountMicros

string (int64 format)

仅限输出。针对超额贷记调整项的税费，以微单位表示。
excessCreditAdjustmentTotalAmountMicros

string (int64 format)

仅限输出。超额贷记调整项总额（以微单位表示）。
regulatoryCostsSubtotalAmountMicros

string (int64 format)

仅限输出。税前监管费用小计金额（以微单位表示）。
regulatoryCostsTaxAmountMicros

string (int64 format)

仅限输出。监管费用税（以微单位表示）。
regulatoryCostsTotalAmountMicros

string (int64 format)

仅限输出。总监管费用金额（以微单位表示）。
exportChargeSubtotalAmountMicros

string (int64 format)

仅限输出。税前出口费用小计金额（以微单位表示）。
exportChargeTaxAmountMicros

string (int64 format)

仅限输出。出口收费税，以微单位表示。
exportChargeTotalAmountMicros

string (int64 format)

仅限输出。出口收费总额（以微单位表示）。
subtotalAmountMicros

string (int64 format)

仅限输出。服务期内可归功于账号的税前小计总金额，以微单位表示。
taxAmountMicros

string (int64 format)

仅限输出。在服务期内归因于帐号的税收总额（以微单位表示）。
totalAmountMicros

string (int64 format)

仅限输出。在服务期内归因于账号的总金额（以微单位表示）。这等于 subtotalAmountMicros 和 taxAmountMicros 的总和。