REST Resource: orders

資源：Order

Order 資源會封裝在 Google Play 上進行交易的完整資訊。包括各種屬性，提供訂單本身、購買的產品，以及與訂單相關事件記錄的詳細資料。

訂單 API 可讓您在 Google Play 生態系統中即時存取訂單資料。您可以擷取一次性訂單和週期性訂單的詳細資訊與中繼資料，包括收費、稅金和退款等交易明細，以及訂閱項目的定價階段等中繼資料。訂單 API 可自動執行訂單管理相關工作，減少透過 Play 管理中心手動檢查的需求。

這項 API 的用途包括：

  • 即時擷取訂單資料 - 使用訂單 ID，在購買後立即取得訂單詳細資料和中繼資料。

  • 訂單更新同步處理 - 定期同步處理訂單更新，以維持最新的訂單資訊記錄。

注意：

  • Orders API 呼叫會計入 Play Developer API 配額，預設為每日 20 萬次，可能不足以同步處理大量訂單記錄。

  • 每次呼叫最多可擷取 1000 筆訂單。建議使用較大的頁面大小，盡量減少配額用量。在 Cloud Console 中查看配額，並視需要申請更多配額。

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 標準化，並使用 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 標準化，並使用 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 商店中列出的商品價格，可能含稅，也可能不含稅。(不計入任何折扣或促銷優惠)。
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,
  "rentalDetails": {
    object (RentalDetails)
  }
}
欄位
quantity

integer

購買的商品數 (適用於購買多件商品)。
offerId

string

一次性購買優惠的優惠 ID。
purchaseOptionId

string

購買選項的 ID。這個欄位會針對購買選項和子類商品設定。如果是購買選項，這個 ID 會識別購買選項本身。如果是變體方案，這個 ID 是指相關聯的購買選項，並與 offerId 共同識別變體方案。
rentalDetails

object (RentalDetails)

租借購買交易的詳細資料。僅在租購時設定。

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 標準化，並使用 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 標準化，並使用 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 標準化，並使用 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 標準化，並使用 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 標準化，並使用 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 reason unspecified. 系統不會使用這個值。
OTHER 訂單退款原因並非此處列出的原因。
CHARGEBACK 訂單遭到交易退單。

PartialRefundEvent

這筆訂單的部分退款事件詳細資料。

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

string (Timestamp format)

部分退款的建立時間。

使用 RFC 3339，產生的輸出內容一律會經過 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 標準化，並使用 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 點數優惠專屬 ID。
pointsCouponValue

object (Money)

Play Points 優待券的貨幣價值。這是優待券提供的折扣，可能不是總金額。只有在使用 Play 點數優待券時才設定。舉例來說，如果 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 Points 點數。舉例來說，如果優待券是 100 點可兌換 $2 美元，則此值為 100。如果優待券與基本方案一併使用，這是指兩者加總的點數。

方法

batchget

 取得訂單清單的訂單詳細資料。

get

 取得單一訂單的詳細資料。

refund

 退還使用者的訂閱項目或應用程式內購訂單款項。