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

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

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