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)
    }
  ],
  "salesChannel": enum (SalesChannel),
  "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)

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

enum (SalesChannel)

订单的原始销售渠道。
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 Points，包括优惠信息、折扣率和积分价值。

州

订单的状态。

枚举
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 商店中的标价，可能含税，也可能不含税。仅排除 Google 资助的折扣。
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),
  "offerPhaseDetails": {
    object (OfferPhaseDetails)
  },
  "servicePeriodStartTime": string,
  "servicePeriodEndTime": string
}
字段
basePlanId

string

订阅的基础方案 ID。
offerId

string

当前订阅优惠的 ID。
offerPhase
(deprecated)

enum (OfferPhase)

已弃用：请改用 offerPhaseDetails。相应订单所涵盖结算周期的定价阶段。
offerPhaseDetails

object (OfferPhaseDetails)

相应订单所对应使用权期限的定价阶段详细信息。
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 订单涵盖免费试用期的权益。

OfferPhaseDetails

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

JSON 表示法 
{

  // Union field phase_details can be only one of the following:
  "freeTrialDetails": {
    object (FreeTrialDetails)
  },
  "introductoryPriceDetails": {
    object (IntroductoryPriceDetails)
  },
  "baseDetails": {
    object (BaseDetails)
  },
  "prorationPeriodDetails": {
    object (ProrationPeriodDetails)
  }
  // End of list of possible types for union field phase_details.
}
字段
联合字段 phase_details。价格阶段详情。phase_details 只能是下列其中一项：
freeTrialDetails

object (FreeTrialDetails)

订单涵盖免费试用期的权益。
introductoryPriceDetails

object (IntroductoryPriceDetails)

订单涵盖一个初次体验周期的费用。
baseDetails

object (BaseDetails)

订单涵盖一个基本价格周期的费用。
prorationPeriodDetails

object (ProrationPeriodDetails)

订单涵盖一个按比例分摊的周期。

FreeTrialDetails

此类型没有字段。

免费试用期定价阶段的详细信息。

IntroductoryPriceDetails

此类型没有字段。

初次体验价定价阶段的详细信息。

BaseDetails

此类型没有字段。

基本价格定价阶段的详细信息。

ProrationPeriodDetails

按比例分摊期限的详细信息。

按比例分摊的时间段可以是方案变更期间计算的时间段，用于涵盖现有授权（如需了解详情，请参阅允许用户升级、降级或更改订阅）；也可以是按比例分摊的时间段，用于使附加服务续订日期与基础方案保持一致（如需了解详情，请参阅适用于购买交易中商品的规则）。

JSON 表示法 
{
  "originalOfferPhase": enum (OfferPhase)
}
字段
originalOfferPhase

enum (OfferPhase)

如果按比例分配的周期包含任何购买的订单项，则表示购买的订单项的原始优惠阶段。例如，从 CHARGE_FULL_PRICE 方案更改产生的按比例分摊期限可能会与用户购买的新产品的订阅优惠的第 1 个优惠阶段合并。在这种情况下，系统会在此处设置原始优惠阶段。

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。对于与基本优惠叠加的优惠券，这是两者花费的总积分。

SalesChannel

订单的原始销售渠道。

枚举
SALES_CHANNEL_UNSPECIFIED 未指定销售渠道。此值未使用。
IN_APP 通过应用内发起标准订单。
PC_EMULATOR 从 PC 模拟器发起的应用内购买订单。
NATIVE_PC 从原生 PC 应用发起的应用内购订单。
PLAY_STORE 通过 Google Play 商店发起的订单。
OUTSIDE_PLAY_STORE 在 Google Play 商店之外发起的订单。

方法

batchget

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

get

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

refund

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

错误代码

此资源相关操作将返回以下 HTTP 错误代码：

错误代码 原因 说明 解决方案