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)

使用者取消訂閱的時間，以從 Epoch 紀元時間算起的毫秒數表示。只有在 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 指定時，才會顯示這個 ID。

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. 已接受：訂閱方案將以接受的價格續訂，除非取消訂閱。價格異動會在日後訂閱方案續訂時生效。請注意，下次續訂時可能不會套用這項變更。

方法

acknowledge

 確認訂閱交易。

cancel

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

defer

 將使用者的訂閱購買交易延後至指定的未來到期時間。

get
(deprecated)

 已淘汰：請改用 purchases.subscriptionsv2.get。

refund
(deprecated)

 已淘汰：請改用 orders.refund。

revoke
(deprecated)

 已淘汰：請改用 purchases.subscriptionsv2.revoke。

錯誤代碼

這項資源的作業會傳回下列 HTTP 錯誤碼：

錯誤代碼 原因 解析度
5xx Google Play 伺服器發生一般錯誤。 重試要求。

如果問題持續發生，請與 Google Play 帳戶管理員聯絡，或提交支援要求。 建議查看 Play 狀態資訊主頁，瞭解是否有已知服務中斷情形。
409 並行更新錯誤。

嘗試更新正在更新的物件。舉例來說，購買交易同時透過呼叫 Play 帳款服務程式庫的 acknowledgePurchase() 方法和 Play Developer API 的 purchases.products.acknowledge 進行確認。

 重試要求。
410 訂閱方案已過期太久，因此無法再查詢。 查詢已過期超過 60 天的訂閱項目時，系統會擲回這個例外狀況。請勿再查詢這些訂閱項目。