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 紀元時間起算)。只有在取消原因為 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 版本，該 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。

入門價格資訊

包含訂閱項目的入門價格資訊。

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」(1 週)、「P1M」(1 個月)、「P3M」(3 個月)、「P6M」(6 個月) 和「P1Y」(1 年)。
introductoryPriceCycles

integer

提供新用戶優惠的帳單週期數。

訂閱取消問卷調查結果

使用者完成訂閱取消流程時提供的資訊 (取消原因問卷調查)。

JSON 表示法 
{
  "cancelSurveyReason": integer,
  "userInputCancelReason": string
}
欄位
cancelSurveyReason

integer

使用者填寫問卷調查的取消原因。可能的值為：0。其他 1. 我不常使用這項服務 2. 技術問題 3. 費用相關原因 4. 我找到了更好的應用程式
userInputCancelReason

string

使用者自訂的輸入取消原因。只有在取消原因為 0 時，才會顯示。

訂閱價格異動

包含訂閱項目的價格異動資訊，可以用來控制應用程式中價格異動的使用者歷程。這可以是透過使用者確認確認或自訂轉換成功的方式。

JSON 表示法 
{
  "newPrice": {
    object (Price)
  },
  "state": integer
}
欄位
newPrice

object (Price)

如果使用者接受價格異動，系統會續訂新的價格。
state

integer

價格異動目前的狀態。可能的值為：0。未完成：待處理的價格變更狀態，正在等待使用者同意。這種情況下，您可以選擇使用 In-App API 要求使用者確認。1. 已接受：如果接受的價格異動，在訂閱項目取消的情況下必須接受該狀態，除非取消訂閱。價格異動的生效日期是訂閱項目的未來日期。請注意，後續續約可能不會發生變更。

方法

acknowledge

 確認訂閱項目購買交易。

cancel

 取消使用者的訂閱項目。

defer

 將使用者的訂閱項目延後到指定的到期時間。

get

 檢查使用者的訂閱項目是否有效，並傳回到期時間。

refund

 使用者的訂閱購買交易會退款，但訂閱在到期前仍然有效，系統會持續進行續訂。

revoke

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