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

這個類別代表 androidpublisher 服務中的 subscriptionPurchase 物件。
startTimeMillis

string (int64 format)

授予訂閱的時間，以自 Epoch 紀元時間起的毫秒數為單位。
expiryTimeMillis

string (int64 format)

訂閱項目的到期時間，以自 Epoch 紀元時間起算的毫秒數為單位。
autoResumeTimeMillis

string (int64 format)

訂閱項目自動恢復的時間，以從 Epoch 紀元時間算起的毫秒數為單位。只有在使用者要求暫停訂閱時才會顯示。
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。如果您使用購買憑證 Z 呼叫這個 API，這個欄位就會設為 Y。如果您使用購買憑證 Y 呼叫此 API，這個欄位會設為 X。如果您使用購買憑證 X 呼叫此 API，系統不會設定這個欄位。
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

第三方服務中的使用者帳戶 ID。只有在帳戶連結發生在訂閱購買流程時，才會顯示。
promotionType

integer

這筆交易所適用的促銷活動類型。只有在購買訂閱時套用促銷優惠時，系統才會設定這個欄位。可能的值為 0。一次性代碼 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」(一週)、「P1M」(一個月)、「P3M」(三個月)、「P6M」(六個月) 和「P1Y」(一年)。
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。待處理：待定價格異動狀態，等待使用者同意。在這個狀態下，您可以選擇使用 In-App API 向使用者尋求確認。1. Accepted：表示已接受價格異動，除非取消，否則訂閱方案會以新價格續約。價格異動會在日後續訂時生效。請注意，下次續訂時可能不會發生變更。

方法

acknowledge

 確認訂閱項目購買交易。

cancel

 取消使用者的訂閱購買交易。

defer

 延後使用者的訂閱購買交易，直到日後指定的到期時間。

get

 檢查使用者的訂閱購買交易是否有效，並傳回其到期時間。

refund

 退還使用者購買的訂閱項目，但訂閱項目仍會在到期時間前有效，並繼續收取費用。

revoke

 退還款項並立即撤銷使用者的訂閱購買交易。