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.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 指定時才會顯示。

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.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

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

refund

退還使用者的訂閱交易款項,但訂閱項目在到期前仍然有效,且訂閱項目將持續延期。

revoke

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