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 规范化（即转换为 UTC 零时区格式并在末尾附加 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。对于 autoRenewing 订阅，如果尚未续订，这是注册订单的订单 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)

第三方服务中的用户账号标识符。
subscribeWithGoogleInfo

object (SubscribeWithGoogleInfo)

与利用“通过 Google 订阅”进行的购买交易相关联的用户个人资料。

SubscriptionState

订阅可能处于的状态，例如订阅是有效还是已取消。订阅购买交易中的商品可以全部是自动续订型方案或全部是预付费方案。

枚举
SUBSCRIPTION_STATE_UNSPECIFIED 未指定订阅状态。
SUBSCRIPTION_STATE_PENDING 订阅已在注册过程中创建，但正在等待付款。在此状态下，所有商品都在等待付款。
SUBSCRIPTION_STATE_ACTIVE 订阅处于有效状态。- (1) 如果订阅是自动续订型方案，则至少一个商品为 autoRenewEnabled 且未过期。- (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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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

第三方服务中的用户账号标识符。

JSON 表示法 
{
  "externalAccountId": string,
  "obfuscatedExternalAccountId": string,
  "obfuscatedExternalProfileId": string
}
字段
externalAccountId

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 指定的情况下才存在。

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 规范化（即转换为 UTC 零时区格式并在末尾附加 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)
  },
  "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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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 规范化（即转换为 UTC 零时区格式并在末尾附加 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

促销代码。

方法

cancel

 取消用户购买的订阅。

get

 获取关于订阅的元数据

revoke

 撤消用户购买的订阅。

错误代码

此资源的操作会返回以下 HTTP 错误代码：

错误代码 原因 分辨率
5xx Google Play 服务器中的一般错误。 请重试您的请求。

如果问题仍然存在，请与您的 Google Play 客户经理联系，或提交支持请求。 不妨查看 Play 状态信息中心，了解是否存在任何已知的中断。
409 并发更新错误。

尝试更新正在更新的对象。例如，通过同时调用 Play 结算库的 acknowledgePurchase() 方法和 Play Developer API 的 purchases.products.acknowledge 来确认购买交易。

 请重试您的请求。
410 相应订阅购买交易已过期太长时间，因此无法再进行查询。 当查询已过期超过 60 天的订阅时抛出。您不应再查询这些订阅。