REST Resource: purchases.subscriptions

リソース: SubscriptionPurchase

SubscriptionPurchase リソースは、ユーザーの定期購入のステータスを示します。

JSON 表現 
{
  "kind": string,
  "startTimeMillis": string,
  "expiryTimeMillis": string,
  "autoResumeTimeMillis": string,
  "autoRenewing": boolean,
  "priceCurrencyCode": string,
  "priceAmountMicros": string,
  "introductoryPriceInfo": {
    object (IntroductoryPriceInfo)
  },
  "countryCode": string,
  "developerPayload": string,
  "paymentState": integer,
  "cancelReason": integer,
  "userCancellationTimeMillis": string,
  "cancelSurveyResult": {
    object (SubscriptionCancelSurveyResult)
  },
  "orderId": string,
  "linkedPurchaseToken": string,
  "purchaseType": integer,
  "priceChange": {
    object (SubscriptionPriceChange)
  },
  "profileName": string,
  "emailAddress": string,
  "givenName": string,
  "familyName": string,
  "profileId": string,
  "acknowledgementState": integer,
  "externalAccountId": string,
  "promotionType": integer,
  "promotionCode": string,
  "obfuscatedExternalAccountId": string,
  "obfuscatedExternalProfileId": string
}
フィールド
kind

string

この kind は、androidpublisher サービスの subscriptionPurchase オブジェクトを示します。
startTimeMillis

string (int64 format)

定期購入が承認された日時をエポックからの経過時間（ミリ秒単位）で示します。
expiryTimeMillis

string (int64 format)

定期購入の期限が切れる日時をエポックからの経過時間（ミリ秒単位）で示します。
autoResumeTimeMillis

string (int64 format)

定期購入が自動再開される日時をエポックからの経過時間（ミリ秒単位）で示します。ユーザーが定期購入の一時停止をリクエストした場合にのみ存在します。
autoRenewing

boolean

現在の有効期限に達した場合に定期購入を自動で更新するかどうか。
priceCurrencyCode

string

定期購入価格の ISO 4217 通貨コード。たとえば、価格がイギリスポンドで指定されている場合、priceCurrencyCode は「GBP」になります。
priceAmountMicros

string (int64 format)

定期購入の価格。外税表示する国の場合、価格に税金は含みません。内税表示する国の場合、価格に税金を含みます。価格は、マイクロ単位で表示します。1,000,000 マイクロ単位が実際の通貨の 1 単位に相当します。たとえば、定期購入価格が €1.99 の場合、priceAmountMicros は「1990000」になります。
introductoryPriceInfo

object (IntroductoryPriceInfo)

定期購入のお試し価格の情報。定期購入がお試し価格で購入された場合にのみ存在します。

このフィールドは、定期購入が現在お試し価格期間にあることを示すものではありません。
countryCode

string

定期購入が承認された時点でのユーザーの請求先住所の国/地域コード（ISO 3166-1 alpha-2 形式）。
developerPayload

string

注文に関する補足情報が含まれる文字列。デベロッパーが指定します。
paymentState

integer

定期購入の支払いの状態。値は次のいずれかです。0. 支払いが保留中、1. 支払いを受領済み、2. 無料試用、3. アップグレード/ダウングレードが保留中

解約、期限切れの定期購入の場合は存在しません。
cancelReason

integer

定期購入が解約された理由、または自動更新されない理由。値は次のいずれかです。0. ユーザーが定期購入を解約したため、1. 請求に関する問題などにより、システムによって定期購入が解約されたため、2. 定期購入が新たな定期購入に置き換えられたため、3. 定期購入がデベロッパーによって解約されたため
userCancellationTimeMillis

string (int64 format)

ユーザーが定期購入を解約した日時をエポックからの経過時間（ミリ秒単位）で示します。cancelReason が 0 の場合にのみ存在します。
cancelSurveyResult

object (SubscriptionCancelSurveyResult)

ユーザーが定期購入解約フロー完了時に提供した情報（解約理由アンケート）。
orderId

string

定期購入に関連付けられた最新の継続注文のオーダー ID。支払いの不承認により定期購入が解約された場合、支払いが不承認だった注文のオーダー ID になります。
linkedPurchaseToken

string

この定期購入が、0. 解約したが失効していない定期購入の再登録、または 1. 以前の定期購入からのアップグレードまたはダウングレードのいずれかに該当する場合は、元の定期購入の購入トークン。

たとえば、ユーザーが初めて定期購入に登録したときにデベロッパーが購入トークン X を受け取ったとします。その定期購入が解約されてから失効する前に再登録フローが行われ、デベロッパーは購入トークン Y を受け取り、さらに定期購入がアップグレードされて購入トークン Z を受け取りました。このシナリオで、この API を購入トークン Z で呼び出すと、このフィールドは Y に設定されます。この API を購入トークン Y で呼び出すと、このフィールドは X に設定されます。この API を購入トークン X で呼び出すと、このフィールドは設定されません。
purchaseType

integer

定期購入の購入タイプ。このフィールドは、標準のアプリ内課金フローを使用して処理された購入ではない場合にのみ設定します。値は次のいずれかです。0. テスト（ライセンス テスト用アカウントでの購入）1. プロモーション（プロモーション コードを使用した購入）
priceChange

object (SubscriptionPriceChange)

利用可能な最新の価格変更情報。定期購入の価格変更が予定されており、まだ適用されていない場合にのみ存在します。

定期購入が新規価格に更新されるか、定期購入が解約されると、価格変更情報は返されなくなります。
profileName

string

定期購入が購入された際のユーザーのプロフィール名。「Google で購読」で購入された場合にのみ存在します。
emailAddress

string

定期購入が購入された際のユーザーのメールアドレス。「Google で購読」で購入された場合にのみ存在します。
givenName

string

定期購入が購入された際のユーザーの名前（名）。「Google で購読」で購入された場合にのみ存在します。
familyName

string

定期購入が購入された際のユーザーの名前（姓）。「Google で購読」で購入された場合にのみ存在します。
profileId

string

定期購入が購入された際のユーザーの Google プロフィール ID。「Google で購読」で購入された場合にのみ存在します。
acknowledgementState

integer

定期購入商品の承認状態。値は次のいずれかです。0. 未承認、1. 確認済み
externalAccountId

string

サードパーティ サービス内のユーザー アカウントの識別子。定期購入フローの一環としてアカウントが連携された場合にのみ存在します。
promotionType

integer

この購入に適用されたプロモーションのタイプ。このフィールドは、定期購入時にプロモーションが適用された場合にのみ設定します。値は次のいずれかです。0. 1 回限りのコード、1. バニティコード
promotionCode

string

この購入に適用されたプロモーション コード。このフィールドは、定期購入時にバニティコードが適用された場合にのみ設定します。
obfuscatedExternalAccountId

string

アプリのユーザー アカウントに一意に関連付けられている難読化されたバージョンの ID。次の購入の場合に存在します。* 定期購入フローの一環としてアカウントが連携された場合。* 購入時に https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedaccountid を使用して指定された場合。
obfuscatedExternalProfileId

string

アプリのユーザー プロファイルに一意に関連付けられている難読化されたバージョンの ID。購入時に https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setobfuscatedprofileid を使用して指定された場合にのみ存在します。

IntroductoryPriceInfo

定期購入のお試し価格情報を含みます。

JSON 表現 
{
  "introductoryPriceCurrencyCode": string,
  "introductoryPriceAmountMicros": string,
  "introductoryPricePeriod": string,
  "introductoryPriceCycles": integer
}
フィールド
introductoryPriceCurrencyCode

string

定期購入のお試し価格の ISO 4217 形式通貨コード。たとえば、価格がイギリスポンドで指定されている場合、priceCurrencyCode は「GBP」になります。
introductoryPriceAmountMicros

string (int64 format)

定期購入のお試し価格（税抜き）。通貨は priceCurrencyCode と同じです。価格は、マイクロ単位で表示します。1,000,000 マイクロ単位が実際の通貨の 1 単位に相当します。たとえば、定期購入価格が €1.99 の場合、priceAmountMicros は「1990000」になります。
introductoryPricePeriod

string

お試し価格の期間。ISO 8601 形式で指定します。「P1W」（1 週間）、「P1M」（1 か月間）、「P3M」（3 か月間）、「P6M」（6 か月間）、「P1Y」（1 年間）といった値が一般的ですが、これらに限定されません。
introductoryPriceCycles

integer

お試し価格を提供する請求対象期間の数。

SubscriptionCancelSurveyResult

ユーザーが定期購入解約フロー完了時に提供した情報（解約理由アンケート）。

JSON 表現 
{
  "cancelSurveyReason": integer,
  "userInputCancelReason": string
}
フィールド
cancelSurveyReason

integer

アンケートでユーザーが選択した解約理由。値は次のいずれかです。0. その他 1. このサービスを十分に活用していない、2. 技術的な問題、3. 料金上の理由、4. もっと良いアプリを見つけた
userInputCancelReason

string

ユーザーが入力したその他の解約理由。cancelReason が 0 の場合にのみ存在します。

SubscriptionPriceChange

定期購入の価格変更情報を含みます。ユーザーに確認を求めたり、問題なく変更できるようにエクスペリエンスを調整したりするなど、アプリ内で価格変更に関わるユーザー ジャーニーをコントロールするために使用できます。

JSON 表現 
{
  "newPrice": {
    object (Price)
  },
  "state": integer
}
フィールド
newPrice

object (Price)

ユーザーが価格変更に同意した場合に定期購入が更新されて適用される新たな価格。
state

integer

価格変更の現在の状態。値は次のいずれかです。0. 未処理: ユーザーの同意を待っており価格変更が保留中の状態。この状態では、アプリ内 API を使用してユーザーの確認を求めることもできます。1. 同意済み: 価格変更が同意された状態。解約されない限り定期購入が更新されて価格変更が適用されます。価格変更は、定期購入が更新される将来の日付から有効になります。定期購入の次回の更新時に価格変更が行われるとは限りません。

メソッド

acknowledge

 定期購入を承認します。

cancel

 ユーザーの定期購入をキャンセルします。

defer

 指定された将来の有効期限までユーザーの定期購入を保留します。

get
(deprecated)

 非推奨: 代わりに purchases.subscriptionsv2.get を使用してください。

refund
(deprecated)

 非推奨: 代わりに orders.refund を使用してください。

revoke
(deprecated)

 非推奨: 代わりに purchases.subscriptionsv2.revoke を使用してください。

エラーコード

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

エラーコード 理由 説明 解決策
400 / 410 subscriptionExpired サブスクリプションが期限切れになったため、リクエストされたオペレーションを実行できません。 定期購入の有効期限を確認します。期限切れの定期購入に対してこの操作を行うことはできません。
400 subscriptionInvalidArgument サブスクリプションのリクエストに無効な引数が指定されました。 API ドキュメントを確認し、必須フィールドがすべて指定され、正しい形式になっていることを確認します。
400 invalidPurchaseState 購入が、リクエストされたオペレーションを実行できる有効な状態ではありません。たとえば、すでに使用済みの購入を承認しようとしている場合や、有効でない定期購入をキャンセルしようとしている場合などです。 オペレーションを試行する前に、対応する Get API を使用してリソースの現在の状態を確認します。リソースがアクションに適した状態であることを確認します。
400 invalidValue リクエストで無効な値が指定されました。多くの場合、これは形式が正しくないか無効な購入トークンに対して返されます。 API リファレンスに基づいて、リクエスト本文またはパラメータの無効なフィールド値を修正します。
400 prepaidSubscriptionNotSupported リクエストされたオペレーションは、プリペイド サブスクリプションではサポートされていません。 オペレーションがサブスクリプション タイプに適用可能であることを確認します。このエラーは、Cancel、Defer、Refund、Revoke などのメソッドに固有のものです。
400 productNotOwnedByUser 提供された購入トークンは有効ですが、ユーザーは現在このアイテムを所有していません。これは、購入が払い戻し、取り消し、または期限切れになった後に確認が行われた場合に発生することがあります。 オペレーションを試行する前に、対応する Get API を使用してリソースの現在の状態を確認します。リソースがアクションに適した状態であることを確認します。
400 purchaseTokenMismatch 指定された購入トークンが、購入、パッケージ名、定期購入 ID、商品 ID と一致しません。 リクエスト内のすべての詳細情報が正しく、相互に対応していることを確認します。
400 required リクエストに必須のフィールドまたはパラメータがありません。 API のドキュメントを参照して、すべての必須フィールドとパラメータが含まれていることを確認します。
400 unsupportedIabType 指定されたアプリ内課金タイプでは、このオペレーションはサポートされていません。 API メソッドが管理対象のアイテムタイプと互換性があることを確認します。
403 userInsufficientPermission リクエストされたオペレーションを実行する権限がユーザーにありません。 認証済みユーザーが Google Play Console で必要な権限を持っていることを確認します。詳細については、 サービス アカウントの使用をご覧ください。
404 notFound リクエストされたリソースが見つかりませんでした。 ID（購入トークン、パッケージ名、商品 ID、定期購入 ID など）が正しいことを確認します。
409 concurrentUpdate 同時に更新されているオブジェクトを更新しようとしました。 指数バックオフを使用してリクエストを再試行します。同じリソースへの同時変更は避けてください。
410 purchaseTokenNoLongerValid 関連付けられたユーザー アカウントが削除されたか、購入記録が存在しなくなったため、購入トークンは永久に無効です。 この購入トークンの使用を中止します。
410 subscriptionNoLongerAvailable 定期購入の有効期限が切れてから時間が経っているため、クエリで定期購入を購入できなくなっています。 このエラーは、サブスクリプションの有効期限が 60 日以上切れていることを示します。これらの定期購入に対してクエリを実行しないでください。
5xx Generic error Google Play サーバーの一般的なエラー。 リクエストを再試行してください。

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