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 錯誤碼：

錯誤代碼 原因 說明 解析度
400 / 410 subscriptionExpired 訂閱方案已過期，無法執行要求的作業。 檢查訂閱方案的到期時間。無法對已過期的訂閱方案執行這項作業。
400 subscriptionInvalidArgument 訂閱要求中提供的引數無效。 請參閱 API 說明文件，確保所有必填欄位都已填入，且格式正確。
400 invalidPurchaseState 購買交易處於無效狀態，無法執行要求的作業。舉例來說，您可能嘗試確認已使用的購買交易，或取消非有效訂閱項目。 嘗試執行作業前，請先使用對應的 Get API 檢查資源的目前狀態。確認資源處於適合執行動作的狀態。
400 invalidValue 要求中提供的值無效。如果購買權杖格式有誤或無效，通常會傳回這個錯誤。 根據 API 參考資料，更正要求主體或參數中的無效欄位值。
400 prepaidSubscriptionNotSupported 預付型訂閱方案不支援要求的作業。 確認作業適用於訂閱類型。這項錯誤只會出現在「取消」、「延後」、「退款」或「撤銷」等方法中。
400 productNotOwnedByUser 提供的購買權杖有效，但使用者目前並未擁有該產品。如果購買交易在確認前已退款、撤銷或過期，就可能發生這種情況。 嘗試執行作業前，請先使用對應的 Get API 檢查資源的目前狀態。確認資源處於適合執行動作的狀態。
400 purchaseTokenMismatch 提供的購買憑證與購買交易、套件名稱、訂閱 ID 或產品 ID 不符。 確認要求中的所有詳細資料皆正確無誤，且彼此相符。
400 required 要求缺少必要欄位或參數。 請參閱 API 說明文件，確認已包含所有必填欄位和參數。
400 unsupportedIabType 指定的應用程式內結帳類型不支援這項作業。 確認 API 方法與要管理的項目類型相容。
403 userInsufficientPermission 使用者沒有足夠的權限可執行要求作業。 確認已驗證的使用者在 Google Play 管理中心具備必要權限。詳情請參閱「 使用服務帳戶」。
404 notFound 找不到要求的資源。 確認 ID (例如購買憑證、套件名稱、產品 ID、訂閱 ID) 正確無誤。
409 concurrentUpdate 嘗試更新正在同步更新的物件。 以指數輪詢方式重試要求。請避免同時修改相同資源。
410 purchaseTokenNoLongerValid 由於相關聯的使用者帳戶已遭刪除，或購買記錄已不存在，因此購買權杖永久無效。 停止使用這個購買交易權杖。
410 subscriptionNoLongerAvailable 訂閱方案已過期太久，因此無法再查詢。 這項錯誤表示訂閱方案已過期超過 60 天。您不應再查詢這些訂閱項目。
5xx Generic error Google Play 伺服器發生一般錯誤。 請重試要求。

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