Voided Purchases API

Google Play Voided Purchases API からは、ユーザーが取り消した購入に関連付けられている注文のリストが提供されます。このリストの情報を基に、ユーザーがそれらの注文から商品にアクセスできないようにする取り消しシステムを実装できます。

この API の対象は、1 回限りのアプリ内注文とアプリ定期購入です。

購入は以下の方法で取り消すことができます。

  • ユーザーが注文に対する払い戻しをリクエストする
  • ユーザーが注文をキャンセルする
  • 注文のチャージバックが行われる

  • デベロッパーが注文のキャンセルまたは払い戻しを行う

  • Google が注文のキャンセルまたは払い戻しを行う

この API を使用すると、特にアプリがゲームの場合、アプリのすべてのユーザーに対してより公平なエクスペリエンスを提供できます。

アクセスを取得する

Voided Purchases API を使用するには、売上情報の表示権限が必要です。認証には、OAuth クライアントまたはサービス アカウントを使用します。サービス アカウントを使用する場合は、アカウント内で「売上レポートの表示」権限を有効にします。

Google Play Developer API への承認済みアクセスを取得する方法について詳しくは、以下のガイドをご覧ください。

取り消し済みの購入を表示する

GET メソッドを使用して、取り消し済みの購入のリストをリクエストします。リクエストには、アプリの完全修飾パッケージ名（例: com.google.android.apps.maps）と、API へのアクセスを取得する際に受け取った承認トークンを含めます。

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

リクエストには以下のパラメータを含めることもできます（各パラメータはオプションです）。

startTime

応答に含める最も古い取り消し済みの購入の、Unix エポックからのミリ秒単位の経過時間。デフォルトでは、startTime は 30 日前に設定されています。

API には、過去 30 日間に取り消された購入のみを表示できます。startTime に指定した値にかかわらず、それ以前に取り消された購入は応答に含まれません。

endTime

応答に含める最も新しい取り消し済みの購入の、Unix エポックからのミリ秒単位の経過時間。デフォルトでは、endTime は現在の時間に設定されています。

maxResults
各応答に含める取り消し済みの購入の最大数。デフォルト値は 1000 です（このパラメータの最大値も 1000 です）。
token
前の応答からの継続トークン。このパラメータを使用すると、表示する結果数を増やすことができます。
type

各応答に含める取り消し済みの購入の種類。0 に設定すると、取り消し済みのアプリ内購入のみが返されます。1 に設定すると、取り消し済みのアプリ内購入と取り消し済みの定期購入の両方が返されます。デフォルト値は 0 です。

includeQuantityBasedPartialRefund

数量ベースの一部払い戻しの取り消し済みの購入を含めるかどうか。複数量の購入にのみ適用されます。true の場合、数量ベースの一部払い戻しの払い戻し量を示す voidedQuantity とあわせて、追加の取り消し済みの購入が返されることがあります。デフォルト値は false です。

応答は、取り消し済みの購入のリストを含む JSON 文字列です。リクエストの maxResults パラメータで指定した値よりも結果数が多い場合、応答に nextPageToken の値が含まれます。この値を次のリクエストに渡すことで、表示する結果数を増やすことができます。リスト内の最初の結果には、最も古い取り消し済みの購入が表示されます。

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

割り当て

Voided Purchases API では、パッケージ単位で以下の割り当てが設定されます。

  • 1 日につき 6,000 クエリ（1 日の開始（終了）は太平洋標準時の午前 0 時）
  • 30 秒間に 30 クエリ

最初のリクエストに関するガイドライン

最初の API リクエストで、アプリで利用可能なデータをすべて取得することをおすすめします。可能性は低いですが、このプロセスによって 1 日の割り当てが使い果たされてしまうこともあります。取り消し済みの購入に関するデータを安全で一貫性のある方法で取得するには、以下の方法を使用することをおすすめします。

  • maxResults パラメータにはデフォルト値を使用します。こうすると、1 日のクエリの割り当てをすべて使用した場合に、6,000,000 件の取り消し済みの購入に関する詳細を取得できます。
  • 応答に nextPageToken の値が含まれている場合、次のリクエストの際にその値を token パラメータに指定します。

ベスト プラクティス

アプリでのこの API を使用する際には、購入を取り消す理由はさまざまであること、すべてのケースで使用できる単一の解決策はないということを覚えておいてください。取り消しに関するポリシーと戦略を設計する際には、ユーザーを念頭に置く必要があります。そのためには、以下の方法を使用することをおすすめします。

  • この API は、望ましくない行動に対処するための包括的な戦略におけるさまざまな要素の 1 つとして使用します。通常、アプリ内アイテムへのアクセスを取り消すことによる効果が高くなるのは、アプリ内購入の価格が妥当なアプリ、望ましくない行動を防止するアプリ設計、望ましくない行動を受け入れない文化を持つ強固なユーザーベース、応答性と効率性に優れたユーザー サポート チャンネルと組み合わせた場合です。
  • すべてのユーザーに対する公平性を確保するために、取り消しポリシーを一律に管理します。
  • 望ましくない行動に対処する場合は、段階的なポリシーを作成することを検討します。たとえば、初期の違反に対してはアプリ内で警告することから始めて、ユーザーによる望ましくない行動が続く場合には応答をエスカレーションします。最終手段として、ユーザーがアプリをまったく操作できないようにすることができます。
  • 取り消しポリシーを導入する場合は、ポリシーを更新するたびに、アプリのサポート チャンネルを使用して変更をユーザーに通知します。変更がアプリで有効になる前に、変更内容を明確に理解するための時間をユーザーに与えます。
  • ユーザーに対する透明性を維持します。アプリ内アイテムへのアクセスを取り消す場合など、措置を講じる場合は必ずユーザーに通知します。理想的には、決定事項に対してユーザーが異議申し立てを行えるようにし、そうした異議申し立てを公平に扱う必要があります。
  • フィードバック フォームとコミュニティ フォーラムを監視して、ユーザーを望ましくない方法での行動に駆り立てる要因と、そのような行動をどのようにして実行に移すのかを理解します。望ましくない行動を防止するための第一歩として、こうした洞察に基づいて対処します。