REST Resource: orders

リソース: Order

Order リソースには、Google Play で行われた取引に関する包括的な情報がカプセル化されています。注文自体、購入された商品、注文に関連するイベントの履歴に関する詳細情報を提供するさまざまな属性が含まれています。

Orders API を使用すると、Google Play エコシステム内の注文データにリアルタイムでアクセスできます。1 回限りの注文と定期注文の両方について、請求額、税額、払い戻し額などの取引明細や、定期購入の価格フェーズなどのメタデータを含む詳細情報を取得できます。Orders API を使用すると、注文管理に関連するタスクを自動化できるため、Google Play デベロッパー コンソールで手動で確認する必要がなくなります。

この API のユースケースは次のとおりです。

  • リアルタイムの注文データ取得 - 注文 ID を使用して購入直後に注文の詳細とメタデータを取得します。

  • 注文更新の同期 - 注文情報の最新の記録を維持するために、注文更新を定期的に同期します。

注:

  • Orders API の呼び出しは、Play Developer API の割り当てにカウントされます。この割り当てはデフォルトで 1 日あたり 20 万件に設定されていますが、大量の注文履歴を同期するには不十分な場合があります。

  • 1 回の呼び出しで取得できる注文の最大数は 1,000 件です。割り当ての使用量を最小限に抑えるには、より大きなページサイズを使用することをおすすめします。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 では、各売上から標準的な取引手数料と第三者の料金を差し引きます。一部の国では、これに VAT も含まれます。
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（国連の国コード）に基づく 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)

1 回だけの購入の詳細。
subscriptionDetails

object (SubscriptionDetails)

定期購入の詳細。
paidAppDetails

object (PaidAppDetails)

有料アプリ購入の詳細。

OneTimePurchaseDetails

1 回だけの購入の詳細。

JSON 表現 
{
  "quantity": integer,
  "offerId": string,
  "purchaseOptionId": string,
  "preorderDetails": {
    object (PreorderDetails)
  "rentalDetails": {
    object (RentalDetails)
  }
}
フィールド
quantity

integer

購入したアイテムの数（複数量のアイテムを購入した場合）。
offerId

string

1 回だけの購入の特典の特典 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 正規化され、小数点以下は 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 の理由が未指定。この値は使用されません。
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 クーポンの金銭的価値。これはクーポンで提供される割引額であり、合計額とは異なる場合があります。Google Play ポイントのクーポンが使用された場合にのみ設定されます。たとえば、100 ポイントで 2 ドル割引のクーポンの場合は 2 ドルです。
pointsDiscountRateMicros

string (int64 format)

Play ポイントのプロモーションで費用が削減される割合。たとえば、100 ポイントで 2 ドル割引のクーポンの場合は 500,000 です。$2 の推定値は 200 ポイントですが、実際の必要ポイント数 100 はその 50% であり、マイクロ単位の 50% は 500,000 です。0 ～ 1,000,000 の範囲。
pointsSpent

string (int64 format)

この注文で使用された Play ポイントの数。たとえば、100 ポイントで $2 割引のクーポンの場合は 100 です。基本特典と併用されたクーポンの場合、両方で消費されたポイントの合計です。

メソッド

batchget

 注文リストの注文詳細を取得します。

get

 1 回の注文の注文詳細を取得します。

refund

 ユーザーの定期購入またはアプリ内購入の注文の払い戻しを行います。

エラーコード

このリソースのオペレーションは、次の HTTP エラーコードを返します。

エラーコード 理由 解決策
5xx Google Play サーバーの一般的なエラー。 リクエストを再試行してください。

問題が解決しない場合は、Google Play アカウント マネージャーにお問い合わせいただくか、サポート リクエストを送信してください。Google Play ステータス ダッシュボードで、既知のサービス停止がないか確認してください。
409 同時実行更新エラー。

更新中のオブジェクトを更新しようとしました。たとえば、Play Billing Library の acknowledgePurchase() メソッドを呼び出すと同時に、Play Developer API の purchases.products.acknowledge を呼び出すことで、購入が承認されます。

 リクエストを再試行してください。