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)

授予订阅内容使用权的时间，以自纪元以来的毫秒数表示。
expiryTimeMillis

string (int64 format)

订阅过期的时间，以自纪元以来的毫秒数表示。
autoResumeTimeMillis

string (int64 format)

订阅将自动恢复的时间，以自纪元以来的毫秒数表示。仅当用户请求暂停订阅时才存在。
autoRenewing

boolean

订阅达到当前过期时间时是否会自动续订。
priceCurrencyCode

string

订阅价格的 ISO 4217 货币代码。例如，如果用英镑指定价格，则 priceCurrencyCode 为“GBP”。
priceAmountMicros

string (int64 format)

订阅价格。对于价格不含税的国家/地区，该价格不含税。对于价格含税的国家/地区，该价格含税。价格以微单位表示，100 万个微单位代表一个单位的货币。例如，如果订阅价格为 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)

用户取消订阅的时间，以自纪元以来的毫秒数表示。仅当 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

第三方服务中的用户账号标识符。仅当在订阅购买流程中进行账号关联时才存在。
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 相同。价格以微单位表示，100 万个微单位代表一个单位的货币。例如，如果订阅价格为 1.99 欧元，则 priceAmountMicros 为 1990000。
introductoryPricePeriod

string

初次体验价时间段，采用 ISO 8601 格式指定。常用值包括（但不限于）“P1W”（一周）、“P1M”（一个月）、“P3M”（三个月）、“P6M”（六个月）和“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

 针对用户购买的订阅进行退款并立即撤消相应订阅。