REST Resource: orders

资源：订单

Order 资源封装了有关 Google Play 上交易的全面信息。它包含各种属性，可提供有关订单本身、所购商品以及与订单相关的事件历史记录的详细信息。

Orders API 可让您实时访问 Google Play 生态系统中的订单数据。您可以检索一次性订单和周期性订单的详细信息和元数据，包括费用、税费和退款等交易详情，以及订阅的定价阶段等元数据。借助 Orders API，您可以自动执行与订单管理相关的任务，从而减少通过 Play 管理中心进行手动检查的需求。

以下是此 API 的一些应用场景：

  • 实时检索订单数据 - 使用订单 ID 在购买后立即检索订单详情和元数据。

  • 订单更新同步 - 定期同步订单更新，以保持最新的订单信息记录。

注意：

  • Orders API 调用会计入您的 Play Developer API 配额，该配额默认为每天 20 万，可能不足以同步大量订单历史记录。

  • 每次调用最多可检索 1,000 个订单。建议使用较大的页面大小，以最大限度地减少配额用量。在 Cloud 控制台中查看您的配额，并在需要时申请更多配额。

JSON 表示法 
{
  "lineItems": [
    {
      object (LineItem)
    }
  ],
  "orderId": string,
  "purchaseToken": string,
  "state": enum (State),
  "createTime": string,
  "lastEventTime": string,
  "buyerAddress": {
    object (BuyerAddress)
  },
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  },
  "orderDetails": {
    object (OrderDetails)
  },
  "orderHistory": {
    object (OrderHistory)
  },
  "developerRevenueInBuyerCurrency": {
    object (Money)
  },
  "pointsDetails": {
    object (PointsDetails)
  }
}
字段
lineItems[]

object (LineItem)

构成相应订单的各个订单项。
orderId

string

订单 ID。
purchaseToken

string

在用户购买订阅或商品时向用户设备提供的令牌。
state

enum (State)

订单的状态。
createTime

string (Timestamp format)

创建订单的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
lastEventTime

string (Timestamp format)

订单的最后一个事件的发生时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
buyerAddress

object (BuyerAddress)

用于计算税费的客户地址信息。如果订单的收单商家是 Google，系统将仅显示国家/地区。
total

object (Money)

在将折扣和税费纳入计算之后，客户最终支付的金额。
tax

object (Money)

作为相应订单的一部分支付的总税费。
orderDetails

object (OrderDetails)

订单创建时的相关详细信息。
orderHistory

object (OrderHistory)

修改订单的事件的详细信息。
developerRevenueInBuyerCurrency

object (Money)

此订单的收入（以买家的币种表示），包括部分退款、税费和手续费的扣减金额。Google 会从每笔销售交易的收入中扣除标准交易手续费和第三方费用，包括一些地区的增值税。
pointsDetails

object (PointsDetails)

应用于订单的 Play 积分，包括优惠信息、折扣率和积分价值。

州

订单的状态。

枚举
STATE_UNSPECIFIED 未指定状态。未使用此值。
PENDING 订单已创建，正在等待处理。
PROCESSED 订单已成功处理。
CANCELED 订单在处理前已被取消。
PENDING_REFUND 所请求的退款正在等待处理。
PARTIALLY_REFUNDED 已退回部分订单款项。
REFUNDED 已退回全额订单款项。

BuyerAddress

用于计算税费的客户地址信息。

JSON 表示法 
{
  "buyerState": string,
  "buyerCountry": string,
  "buyerPostcode": string
}
字段
buyerState

string

买家地址所属国家/地区的顶级行政区划。如果订单的收单商家是 Google，此信息将不包含在内。
buyerCountry

string

基于 ISO-3166-1 Alpha-2（联合国国家/地区代码）的国家/地区代码，由两个字母组成。
buyerPostcode

string

地址中的邮政编码。如果订单的收单商家是 Google，此信息将不包含在内。

OrderDetails

订单创建时的相关详细信息。

JSON 表示法 
{
  "taxInclusive": boolean
}
字段
taxInclusive

boolean

指示定价是否含税。

LineItem

订单项的详细信息。

JSON 表示法 
{
  "productTitle": string,
  "productId": string,
  "listingPrice": {
    object (Money)
  },
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  },

  // Union field details can be only one of the following:
  "oneTimePurchaseDetails": {
    object (OneTimePurchaseDetails)
  },
  "subscriptionDetails": {
    object (SubscriptionDetails)
  },
  "paidAppDetails": {
    object (PaidAppDetails)
  }
  // End of list of possible types for union field details.
}
字段
productTitle

string

开发者指定的商品名称。以买家的当地语言显示。例如：coins（虚拟货币）、monthly subscription（按月订阅）等。
productId

string

所购买商品的 ID 或应用内 SKU（例如：“monthly001”或“com.some.thing.inapp1”）。
listingPrice

object (Money)

商品在 Play 商店中的标价，可能含税，也可能不含税。不含任何折扣或促销优惠。
total

object (Money)

在将折扣和税费纳入计算之后，用户为相应订单项支付的总金额。
tax

object (Money)

用户为相应订单项支付的税费。

联合字段 details。

details 只能是下列其中一项：
oneTimePurchaseDetails

object (OneTimePurchaseDetails)

一次性购买交易的详细信息。
subscriptionDetails

object (SubscriptionDetails)

订阅购买交易的详细信息。
paidAppDetails

object (PaidAppDetails)

购买的付费应用的详细信息。

OneTimePurchaseDetails

一次性购买交易的详细信息。

JSON 表示法 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "preorderDetails": {
    object (PreorderDetails)
  "rentalDetails": {
    object (RentalDetails)
  }
}
字段
quantity

integer

购买的商品的数量（针对购买多件商品的交易）。
offerId

string

一次性购买交易的优惠 ID。
purchaseOptionId

string

购买选项的 ID。此字段针对购买选项和变体优惠均设置。对于购买选项，此 ID 用于标识购买选项本身。对于变体优惠，此 ID 指的是关联的购买选项，并与 offerId 结合使用来标识变体优惠。
preorderDetails

object (PreorderDetails)

预订的详细信息。仅为预订购买交易设置此字段。
rentalDetails

object (RentalDetails)

租借购买交易的详细信息。仅当购买交易为租借交易时才设置此字段。

PreorderDetails

此类型没有字段。

预订购买交易的详细信息。

RentalDetails

此类型没有字段。

租赁购买交易的详细信息。

SubscriptionDetails

订阅购买交易的详细信息。

JSON 表示法 
{
  "basePlanId": string,
  "offerId": string,
  "offerPhase": enum (OfferPhase),
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
字段
basePlanId

string

订阅的基础方案 ID。
offerId

string

当前订阅优惠的优惠 ID。
offerPhase

enum (OfferPhase)

相应订单采用的结算周期的定价阶段。
servicePeriodStartTime

string (Timestamp format)

相应订单采用的结算周期的开始时间。这是在处理订单时记录的结算/服务周期开始时间，应仅用于记账目的。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
servicePeriodEndTime

string (Timestamp format)

相应订单采用的结算周期的结束时间。这是在处理订单时记录的结算/服务周期结束时间，应仅用于记账目的。如需获取订阅服务周期的当前结束时间，请使用 purchases.subscriptionsv2.get。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

OfferPhase

相应订单所对应的使用权期限的定价阶段。

枚举
OFFER_PHASE_UNSPECIFIED 未指定优惠阶段。未使用此值。
BASE 订单对应基本价格期间。
INTRODUCTORY 订单对应初次体验价期间。
FREE_TRIAL 订单对应免费试用期。

PaidAppDetails

此类型没有字段。

购买的付费应用的详细信息。

OrderHistory

修改订单的事件的详细信息。

JSON 表示法 
{
  "partialRefundEvents": [
    {
      object (PartialRefundEvent)
    }
  ],
  "processedEvent": {
    object (ProcessedEvent)
  },
  "cancellationEvent": {
    object (CancellationEvent)
  },
  "refundEvent": {
    object (RefundEvent)
  }
}
字段
partialRefundEvents[]

object (PartialRefundEvent)

相应订单的部分退款事件的详细信息。
processedEvent

object (ProcessedEvent)

订单处理时间的详细信息。
cancellationEvent

object (CancellationEvent)

订单取消时间的详细信息。
refundEvent

object (RefundEvent)

订单全额退款的详细信息。

ProcessedEvent

订单处理时间的详细信息。

JSON 表示法 
{
  "eventTime": string
}
字段
eventTime

string (Timestamp format)

处理订单的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

CancellationEvent

订单取消时间的详细信息。

JSON 表示法 
{
  "eventTime": string
}
字段
eventTime

string (Timestamp format)

取消订单的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

RefundEvent

订单全额退款的详细信息。

JSON 表示法 
{
  "eventTime": string,
  "refundDetails": {
    object (RefundDetails)
  },
  "refundReason": enum (RefundReason)
}
字段
eventTime

string (Timestamp format)

订单全额退款的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
refundDetails

object (RefundDetails)

全额退款的详细信息。
refundReason

enum (RefundReason)

订单退款的原因。

RefundDetails

部分退款或全额退款的详细信息。

JSON 表示法 
{
  "total": {
    object (Money)
  },
  "tax": {
    object (Money)
  }
}
字段
total

object (Money)

退款总额，包含税费。
tax

object (Money)

退还的税费金额。

RefundReason

订单退款的原因。

枚举
REFUND_REASON_UNSPECIFIED 未指定 orders.refund 的原因。未使用此值。
OTHER 订单因此处未列出的其他原因而退款。
CHARGEBACK 订单已退单。

PartialRefundEvent

相应订单的部分退款事件的详细信息。

JSON 表示法 
{
  "createTime": string,
  "processTime": string,
  "state": enum (State),
  "refundDetails": {
    object (RefundDetails)
  }
}
字段
createTime

string (Timestamp format)

创建部分退款的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
processTime

string (Timestamp format)

处理部分退款的时间。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
state

enum (State)

部分退款的状态。
refundDetails

object (RefundDetails)

部分退款的详细信息。

州

部分退款的状态。

枚举
STATE_UNSPECIFIED 未指定状态。未使用此值。
PENDING 部分退款已创建，但尚未得到处理。
PROCESSED_SUCCESSFULLY 部分退款已成功完成处理。

PointsDetails

与应用于订单的任何 Play 积分相关的详细信息。

JSON 表示法 
{
  "pointsOfferId": string,
  "pointsCouponValue": {
    object (Money)
  },
  "pointsDiscountRateMicros": string,
  "pointsSpent": string
}
字段
pointsOfferId

string

相应订单所用 Play Points 优惠的唯一 ID。
pointsCouponValue

object (Money)

Play Points 优惠券的货币价值。这是优惠券提供的折扣，可能不是总金额。仅在已使用 Play Points 优惠券时设置。例如，对于“100 积分兑换 2 美元优惠券”的优惠，此值为 2 美元。
pointsDiscountRateMicros

string (int64 format)

Play Points 促销活动可降低的费用百分比。例如，对于 100 积分兑换 2 美元优惠券，此值为 500,000。由于 $2 的估计点数为 200，但实际所需点数 100 是此估计值的 50%，而 50% 的微币值为 500,000。介于 0 和 1,000,000 之间。
pointsSpent

string (int64 format)

相应订单中使用的 Play 积分数量。例如，对于“2 美元优惠券，可兑换 100 积分”的优惠，此值为 100。对于与基本优惠叠加的优惠券，这是两者花费的总积分。

方法

batchget

 获取一系列订单的订单详细信息。

get

 获取单笔订单的订单详细信息。

refund

 针对用户订阅或应用内购买订单进行退款。

错误代码

此资源的操作会返回以下 HTTP 错误代码：

错误代码 原因 分辨率
5xx Google Play 服务器中的一般错误。 请重试您的请求。

如果问题仍然存在，请与您的 Google Play 客户经理联系，或提交支持请求。 不妨查看 Play 状态信息中心，了解是否存在任何已知的中断。
409 并发更新错误。

尝试更新正在更新的对象。例如，通过同时调用 Play 结算库的 acknowledgePurchase() 方法和 Play Developer API 的 purchases.products.acknowledge 来确认购买交易。

 请重试您的请求。