REST Resource: purchases.subscriptionsv2

資源：SubscriptionPurchaseV2

指出使用者的訂閱購買交易狀態。

JSON 表示法 
{
  "kind": string,
  "regionCode": string,
  "lineItems": [
    {
      object (SubscriptionPurchaseLineItem)
    }
  ],
  "startTime": string,
  "subscriptionState": enum (SubscriptionState),
  "latestOrderId": string,
  "linkedPurchaseToken": string,
  "pausedStateContext": {
    object (PausedStateContext)
  },
  "canceledStateContext": {
    object (CanceledStateContext)
  },
  "testPurchase": {
    object (TestPurchase)
  },
  "acknowledgementState": enum (AcknowledgementState),
  "externalAccountIdentifiers": {
    object (ExternalAccountIdentifiers)
  },
  "subscribeWithGoogleInfo": {
    object (SubscribeWithGoogleInfo)
  }
}
欄位
kind

string

這類代表 androidpublisher 服務中的 SubscriptionPurchaseV2 物件。
regionCode

string

使用者獲得訂閱授權時的 ISO 3166-1 alpha-2 帳單國家/地區代碼。
lineItems[]

object (SubscriptionPurchaseLineItem)

訂閱交易的項目層級資訊。同一筆交易中的項目應全為 AutoRenewingPlan 或全為 PrepaidPlan。
startTime

string (Timestamp format)

授予訂閱的時間。未設定待處理的訂閱項目 (訂閱項目已建立，但註冊時尚未付款)。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
subscriptionState

enum (SubscriptionState)

訂閱方案的目前狀態。
latestOrderId
(deprecated)

string

已淘汰：請改用 lineItems.latest_successful_order_id。與訂閱方案購買交易相關聯的最新訂單 ID。如為自動續訂型訂閱項目，如果尚未續訂，這就是註冊訂單的訂單 ID；如果已續訂，這就是最後一筆週期性訂單的 ID (成功、待處理或遭拒的訂單)。如果是預付型訂閱方案，這是與查詢的購買憑證相關聯的訂單 ID。
linkedPurchaseToken

string

如果訂閱項目屬於下列情況，請提供舊訂閱項目的購買憑證： * 取消後重新註冊但未過期的訂閱項目 * 從先前的訂閱項目升級/降級。 * 從預付型方案改為自動續訂型方案。* 將自動續訂型訂閱方案改為預付型。* 為預付型訂閱方案儲值。
pausedStateContext

object (PausedStateContext)

暫停訂閱的額外背景資訊。只有在訂閱項目的 subscriptionState 目前為 SUBSCRIPTION_STATE_PAUSED 時才會顯示。
canceledStateContext

object (CanceledStateContext)

取消訂閱的額外背景資訊。只有在訂閱項目的 subscriptionState 目前為 SUBSCRIPTION_STATE_CANCELED 或 SUBSCRIPTION_STATE_EXPIRED 時才會顯示。
testPurchase

object (TestPurchase)

僅在訂閱項目購買交易為測試交易時顯示。
acknowledgementState

enum (AcknowledgementState)

訂閱項目的確認狀態。
externalAccountIdentifiers

object (ExternalAccountIdentifiers)

第三方服務中的使用者帳戶 ID。
subscribeWithGoogleInfo

object (SubscribeWithGoogleInfo)

與透過「使用 Google 訂閱」服務進行的購買交易相關聯的使用者設定檔。

SubscriptionState

訂閱項目的可能狀態，例如有效或已取消。訂閱項目內的所有商品必須都是自動續訂型方案或預付方案。

列舉
SUBSCRIPTION_STATE_UNSPECIFIED 未指定訂閱狀態。
SUBSCRIPTION_STATE_PENDING 申請時已建立訂閱方案，但尚未付款。在此狀態下，所有項目都處於等待付款狀態。
SUBSCRIPTION_STATE_ACTIVE 訂閱方案有效。- (1) 如果訂閱方案會自動續訂，則至少有一項商品已啟用自動續訂功能，且未過期。- (2) 如果訂閱方案為預付方案，至少有一項商品未過期。
SUBSCRIPTION_STATE_PAUSED 訂閱方案已暫停。只有在訂閱方案為自動續訂型方案時，才能使用此狀態。處於這種狀態時，所有項目都會暫停。
SUBSCRIPTION_STATE_IN_GRACE_PERIOD 訂閱方案處於寬限期。只有在訂閱方案為自動續訂型方案時，才能使用此狀態。在這個狀態下，所有項目都處於寬限期。
SUBSCRIPTION_STATE_ON_HOLD 訂閱方案已暫停 (停權)。只有在訂閱方案為自動續訂型方案時，才能使用此狀態。處於這種狀態時，所有項目都會暫緩處理。
SUBSCRIPTION_STATE_CANCELED 訂閱已取消，但尚未到期。只有在訂閱方案為自動續訂型方案時，才能使用此狀態。所有項目的 autoRenewEnabled 都設為 false。
SUBSCRIPTION_STATE_EXPIRED 訂閱方案已過期。所有項目的 expiryTime 都已過期。
SUBSCRIPTION_STATE_PENDING_PURCHASE_CANCELED 已取消待處理的訂閱交易。如果這筆待處理的交易是現有訂閱項目，請使用 linkedPurchaseToken 取得該訂閱項目的目前狀態。

PausedStateContext

暫停訂閱狀態的相關資訊。

JSON 表示法 
{
  "autoResumeTime": string
}
欄位
autoResumeTime

string (Timestamp format)

系統自動恢復訂閱的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

CanceledStateContext

處於 SUBSCRIPTION_STATE_CANCELED 或 SUBSCRIPTION_STATE_EXPIRED 狀態的訂閱項目專屬資訊。

JSON 表示法 
{

  // Union field cancellation_reason can be only one of the following:
  "userInitiatedCancellation": {
    object (UserInitiatedCancellation)
  },
  "systemInitiatedCancellation": {
    object (SystemInitiatedCancellation)
  },
  "developerInitiatedCancellation": {
    object (DeveloperInitiatedCancellation)
  },
  "replacementCancellation": {
    object (ReplacementCancellation)
  }
  // End of list of possible types for union field cancellation_reason.
}
欄位
聯集欄位 cancellation_reason。取消訂閱的原因。cancellation_reason 只能是下列其中一項：
userInitiatedCancellation

object (UserInitiatedCancellation)

使用者已取消訂閱。
systemInitiatedCancellation

object (SystemInitiatedCancellation)

系統取消訂閱方案，例如因為帳單問題。
developerInitiatedCancellation

object (DeveloperInitiatedCancellation)

開發人員已取消訂閱。
replacementCancellation

object (ReplacementCancellation)

訂閱方案已由新方案取代。

UserInitiatedCancellation

使用者主動取消訂閱的相關資訊。

JSON 表示法 
{
  "cancelSurveyResult": {
    object (CancelSurveyResult)
  },
  "cancelTime": string
}
欄位
cancelSurveyResult

object (CancelSurveyResult)

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

string (Timestamp format)

使用者取消訂閱的時間。使用者在這段時間過後可能仍可存取訂閱項目。使用 lineItems.expiry_time 判斷使用者是否仍有存取權。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

CancelSurveyResult

使用者取消訂閱時，取消問卷調查的結果。

JSON 表示法 
{
  "reason": enum (CancelSurveyReason),
  "reasonUserInput": string
}
欄位
reason

enum (CancelSurveyReason)

使用者在取消訂閱問卷調查中選取的原因。
reasonUserInput

string

僅為 CANCEL_SURVEY_REASON_OTHERS 設定。這是使用者對問卷調查的自由形式回覆。

CancelSurveyReason

使用者在取消訂閱問卷調查中選取的原因。

列舉
CANCEL_SURVEY_REASON_UNSPECIFIED 取消問卷調查的原因不明。
CANCEL_SURVEY_REASON_NOT_ENOUGH_USAGE 訂閱方案使用量不足。
CANCEL_SURVEY_REASON_TECHNICAL_ISSUES 使用應用程式時發生技術問題。
CANCEL_SURVEY_REASON_FOUND_BETTER_APP 使用者找到了更好的應用程式。
CANCEL_SURVEY_REASON_OTHERS 其他原因。

SystemInitiatedCancellation

這個類型沒有任何欄位。

Google 系統發起的取消作業專屬資訊。

DeveloperInitiatedCancellation

這個類型沒有任何欄位。

開發人員發起的取消作業專用資訊。

ReplacementCancellation

這個類型沒有任何欄位。

因更換訂閱方案而取消訂閱的相關資訊。

TestPurchase

這個類型沒有任何欄位。

這筆訂閱交易是否為測試交易。

AcknowledgementState

訂閱項目的可能確認狀態。

列舉
ACKNOWLEDGEMENT_STATE_UNSPECIFIED 未指定確認狀態。
ACKNOWLEDGEMENT_STATE_PENDING 訂閱尚未確認。
ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED 已確認訂閱。

ExternalAccountIdentifiers

第三方服務中的使用者帳戶 ID。

JSON 表示法 
{
  "externalAccountId": string,
  "obfuscatedExternalAccountId": string,
  "obfuscatedExternalProfileId": string
}
欄位
externalAccountId

string

第三方服務中的使用者帳戶 ID。只有在帳戶連結是訂閱購買流程的一部分時，才會顯示這項資訊。
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。

SubscribeWithGoogleInfo

透過「使用 Google 訂閱」服務進行購買的相關資訊。

JSON 表示法 
{
  "profileId": string,
  "profileName": string,
  "emailAddress": string,
  "givenName": string,
  "familyName": string
}
欄位
profileId

string

使用者購買訂閱項目時的 Google 設定檔 ID。
profileName

string

購買訂閱方案時的使用者設定檔名稱。
emailAddress

string

購買訂閱方案時使用的使用者電子郵件地址。
givenName

string

購買訂閱項目時使用者的名字。
familyName

string

購買訂閱項目時的使用者姓氏。

SubscriptionPurchaseLineItem

訂閱交易的項目層級資訊。

JSON 表示法 
{
  "productId": string,
  "expiryTime": string,
  "latestSuccessfulOrderId": string,

  // Union field plan_type can be only one of the following:
  "autoRenewingPlan": {
    object (AutoRenewingPlan)
  },
  "prepaidPlan": {
    object (PrepaidPlan)
  }
  // End of list of possible types for union field plan_type.
  "offerDetails": {
    object (OfferDetails)
  },

  // Union field deferred_item_change can be only one of the following:
  "deferredItemReplacement": {
    object (DeferredItemReplacement)
  },
  "deferredItemRemoval": {
    object (DeferredItemRemoval)
  }
  // End of list of possible types for union field deferred_item_change.
  "signupPromotion": {
    object (SignupPromotion)
  }
}
欄位
productId

string

所購買產品的 ID (例如「monthly001」)。
expiryTime

string (Timestamp format)

訂閱方案到期時間。除非延長存取權 (例如續訂)，否則訂閱方案將於此時到期。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
latestSuccessfulOrderId

string

與這個項目相關聯的最新成功訂單 ID。如果使用者尚未擁有該項目 (例如延後更換的項目)，則不會顯示這項資訊。
聯集欄位 plan_type。訂閱方案類型。plan_type 只能是下列其中一項：
autoRenewingPlan

object (AutoRenewingPlan)

這項商品會自動續訂。
prepaidPlan

object (PrepaidPlan)

商品已預付。
offerDetails

object (OfferDetails)

這項商品的優惠詳細資料。
聯集欄位 deferred_item_change。如果項目有延遲變更，就會顯示這個欄位。你可以移除或更換。deferred_item_change 只能是下列其中一項：
deferredItemReplacement

object (DeferredItemReplacement)

延後換貨的相關資訊。
deferredItemRemoval

object (DeferredItemRemoval)

延後移除項目的相關資訊。
signupPromotion

object (SignupPromotion)

這項商品的促銷活動詳細資料。只有在註冊時套用促銷活動時才設定。

AutoRenewingPlan

自動續訂方案的相關資訊。

JSON 表示法 
{
  "autoRenewEnabled": boolean,
  "recurringPrice": {
    object (Money)
  },
  "priceChangeDetails": {
    object (SubscriptionItemPriceChangeDetails)
  },
  "installmentDetails": {
    object (InstallmentPlan)
  }
}
欄位
autoRenewEnabled

boolean

如果訂閱方案目前設為自動續訂 (例如使用者尚未取消訂閱)
recurringPrice

object (Money)

自動續約方案目前的週期性價格。請注意，價格不含折扣，且未稅價格不含稅金。如需交易詳細資料，請改為呼叫 orders.get API。
priceChangeDetails

object (SubscriptionItemPriceChangeDetails)

自訂閱註冊以來，該項目最近一次的價格異動資訊。
installmentDetails

object (InstallmentPlan)

自動續訂方案的分期付款方案承諾和相關資訊。

SubscriptionItemPriceChangeDetails

訂閱項目的價格異動相關資訊。

JSON 表示法 
{
  "newPrice": {
    object (Money)
  },
  "priceChangeMode": enum (PriceChangeMode),
  "priceChangeState": enum (PriceChangeState),
  "expectedNewPriceChargeTime": string
}
欄位
newPrice

object (Money)

訂閱項目的新定期付款價格。
priceChangeMode

enum (PriceChangeMode)

價格變更模式會指定訂閱項目價格的變更方式。
priceChangeState

enum (PriceChangeState)

說明目前價格異動的狀態。
expectedNewPriceChargeTime

string (Timestamp format)

價格異動對使用者生效的續訂時間。如果續訂時間因暫停等情況而延後，這項時間也可能會隨之變更。只有在價格異動尚未生效時，才會填入這個欄位。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

PriceChangeMode

價格變更模式。

列舉
PRICE_CHANGE_MODE_UNSPECIFIED 未指定價格異動模式。這個值絕不應設定。
PRICE_DECREASE 訂閱價格調降。
PRICE_INCREASE 訂閱價格調漲，且使用者必須接受。
OPT_OUT_PRICE_INCREASE 如果訂閱價格調漲，且採用被動接受型漲價方案。

PriceChangeState

價格變更的狀態。

列舉
PRICE_CHANGE_STATE_UNSPECIFIED 未指定價格異動狀態。請勿使用此值。
OUTSTANDING 等待使用者同意價格變更。
CONFIRMED 確認價格異動會套用至使用者。
APPLIED 價格異動已生效，也就是說，系統已開始向使用者收取新價格。
CANCELED 價格異動已取消。

InstallmentPlan

分期付款方案的相關資訊。

JSON 表示法 
{
  "initialCommittedPaymentsCount": integer,
  "subsequentCommittedPaymentsCount": integer,
  "remainingCommittedPaymentsCount": integer,
  "pendingCancellation": {
    object (PendingCancellation)
  }
}
欄位
initialCommittedPaymentsCount

integer

使用者最初約定的付款總數。
subsequentCommittedPaymentsCount

integer

每個約期結束後，使用者必須支付的款項總數。如果為空白，表示分期付款方案在初始約期結束後，會恢復為一般自動續訂方案。
remainingCommittedPaymentsCount

integer

這個續訂週期內，尚未支付的承諾付款總額。
pendingCancellation

object (PendingCancellation)

如果有的話，這項分期付款方案目前處於待取消狀態。使用者完成所有承諾的付款後，系統才會取消訂閱。

PendingCancellation

這個類型沒有任何欄位。

這項指標會指出虛擬分期付款方案是否處於待取消狀態。使用者完成所有承諾的付款後，系統才會取消訂閱。

PrepaidPlan

預付方案相關資訊。

JSON 表示法 
{
  "allowExtendAfterTime": string
}
欄位
allowExtendAfterTime

string (Timestamp format)

如果有的話，這是指預付方案允許購買儲值金的時間。過期的預付方案不會顯示這項資訊。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

OfferDetails

與購買項目相關的優惠詳細資料。

JSON 表示法 
{
  "offerTags": [
    string
  ],
  "basePlanId": string,
  "offerId": string
}
欄位
offerTags[]

string

與優惠相關聯的最新優惠標記。包括從基本方案沿用的標記。
basePlanId

string

基本方案 ID。適用於所有基本方案和優惠。
offerId

string

優惠 ID。僅適用於折扣優惠。

DeferredItemReplacement

延後換貨的相關資訊。

JSON 表示法 
{
  "productId": string
}
欄位
productId

string

要取代現有 productId 的 productId。

DeferredItemRemoval

這個類型沒有任何欄位。

延後換貨的相關資訊。

SignupPromotion

購買這項商品時已套用促銷活動。

JSON 表示法 
{

  // Union field promotion_type can be only one of the following:
  "oneTimeCode": {
    object (OneTimeCode)
  },
  "vanityCode": {
    object (VanityCode)
  }
  // End of list of possible types for union field promotion_type.
}
欄位
聯集欄位 promotion_type。商品套用的促銷活動類型。promotion_type 只能是下列其中一項：
oneTimeCode

object (OneTimeCode)

已套用一次性代碼。
vanityCode

object (VanityCode)

已套用自訂代碼。

OneTimeCode

這個類型沒有任何欄位。

一次性促銷代碼。

VanityCode

可重複使用的預先定義促銷代碼。

JSON 表示法 
{
  "promotionCode": string
}
欄位
promotionCode

string

促銷代碼。

方法

get

 取得訂閱項目的中繼資料

revoke

 撤銷使用者的訂閱購買交易。