Method: customers.invoices.list

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

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

HTTP 请求

GET https://googleads.googleapis.com/v14/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。它作为“账单编号”显示在账单 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”。

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,该 ID 在账单 PDF 中显示为“帐号 ID”。客户资源名称采用以下格式:

customers/{customerId}

customerDescriptiveName

string

仅供输出。帐号预算客户的描述性名称。它在账单 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 的总和。