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)
  },
  "outOfAppPurchaseContext": {
    object (OutOfAppPurchaseContext)
  }
}
欄位
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 訂閱」服務進行的購買交易相關聯的使用者設定檔。
outOfAppPurchaseContext

object (OutOfAppPurchaseContext)

應用程式外購的額外背景資訊。這項資訊只會顯示在透過 Google Play 訂閱中心重新訂閱的交易中 (即先前訂閱的相同產品到期後，再次訂閱)。確認訂閱後，系統就會移除這個欄位。

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)
  },
  "itemReplacement": {
    object (ItemReplacement)
  }
}
欄位
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)

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

object (ItemReplacement)

要更換的商品詳細資料。如果這項商品取代了先前訂閱方案中的其他商品，系統才會填入這個欄位，且只會在購買時間後的 60 天內提供。

AutoRenewingPlan

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

JSON 表示法 
{
  "autoRenewEnabled": boolean,
  "recurringPrice": {
    object (Money)
  },
  "priceChangeDetails": {
    object (SubscriptionItemPriceChangeDetails)
  },
  "installmentDetails": {
    object (InstallmentPlan)
  },
  "priceStepUpConsentDetails": {
    object (PriceStepUpConsentDetails)
  }
}
欄位
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

這個類型沒有任何欄位。

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

PriceStepUpConsentDetails

需要使用者同意的價格調漲相關資訊。

JSON 表示法 
{
  "state": enum (ConsentState),
  "consentDeadlineTime": string,
  "newPrice": {
    object (Money)
  }
}
欄位
state

enum (ConsentState)

僅供輸出。價格調漲同意聲明的狀態。
consentDeadlineTime

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"。
newPrice

object (Money)

新價格，需要使用者同意。

ConsentState

價格調漲同意聲明的狀態。

列舉
CONSENT_STATE_UNSPECIFIED 未指定同意聲明狀態。
PENDING 使用者尚未提供同意聲明。
CONFIRMED 使用者已同意，新價格即將生效。
COMPLETED 使用者已同意，新價格已生效。

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

促銷代碼。

ItemReplacement

要更換的訂閱項目詳細資料。

JSON 表示法 
{
  "productId": string,
  "replacementMode": enum (ReplacementMode),
  "basePlanId": string,
  "offerId": string
}
欄位
productId

string

要更換的訂閱項目產品 ID。
replacementMode

enum (ReplacementMode)

購買時套用的取代模式。
basePlanId

string

要更換的訂閱項目基本方案 ID。
offerId

string

要更換的訂閱項目委刊項優惠 ID (如適用)。

ReplacementMode

訂閱項目的取代模式。

列舉
REPLACEMENT_MODE_UNSPECIFIED 未指定取代模式。
WITH_TIME_PRORATION 系統會按比例計算新方案的費用，並從舊方案中扣除。
CHARGE_PRORATED_PRICE 系統會按比例收取新方案的費用。
WITHOUT_PRORATION 新方案會取代舊方案，且不會按比例計算時間。
CHARGE_FULL_PRICE 系統會向使用者收取新方案的全額費用。
DEFERRED 舊方案會取消，新方案則會在舊方案到期後生效。
KEEP_EXISTING 更換後，方案不會變更。

OutOfAppPurchaseContext

應用程式外購物的相關資訊。

JSON 表示法 
{
  "expiredExternalAccountIdentifiers": {
    object (ExternalAccountIdentifiers)
  },
  "expiredPurchaseToken": string
}
欄位
expiredExternalAccountIdentifiers

object (ExternalAccountIdentifiers)

此 SKU 上次過期訂閱方案的使用者帳戶 ID。
expiredPurchaseToken

string

最後一個過期訂閱項目的購買交易權杖。如果資料庫中儲存了 purchaseToken 與使用者之間的連結，這個權杖就只能用來識別使用者。如果過期超過 60 天，就無法用於呼叫 Google Developer API。

方法

cancel

 為使用者取消訂閱購買交易。

get

 取得訂閱項目的中繼資料

revoke

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

錯誤代碼

這項資源的作業會傳回下列 HTTP 錯誤碼：

錯誤代碼 原因 解析度
5xx Google Play 伺服器發生一般錯誤。 重試要求。

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

嘗試更新正在更新的物件。舉例來說，購買交易同時透過呼叫 Play 帳款服務程式庫的 acknowledgePurchase() 方法和 Play Developer API 的 purchases.products.acknowledge 進行確認。

 重試要求。
410 訂閱方案已過期太久，因此無法再查詢。 查詢已過期超過 60 天的訂閱項目時，系統會擲回這個例外狀況。請勿再查詢這些訂閱項目。