REST Resource: purchases.subscriptionsv2

资源:SubscriptionPurchaseV2

表示用户订阅购买交易的状态。

JSON 表示法
{
  "kind": string,
  "regionCode": string,
  "lineItems": [
    {
      object (SubscriptionPurchaseLineItem)
    }
  ],
  "startTime": string,
  "subscriptionState": enum (SubscriptionState),
  "linkedPurchaseToken": string,
  "pausedStateContext": {
    object (PausedStateContext)
  },
  "canceledStateContext": {
    object (CanceledStateContext)
  },
  "testPurchase": {
    object (TestPurchase)
  },
  "acknowledgementState": enum (AcknowledgementState),
  "externalAccountIdentifiers": {
    object (ExternalAccountIdentifiers)
  },
  "subscribeWithGoogleInfo": {
    object (SubscribeWithGoogleInfo)
  },
  "etag": string,
  "outOfAppPurchaseContext": {
    object (OutOfAppPurchaseContext)
  },
  "onHoldStateContext": {
    object (OnHoldStateContext)
  },
  "inGracePeriodStateContext": {
    object (InGracePeriodStateContext)
  }
}
字段
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)

订阅的当前状态。

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 订阅”进行的购买交易相关联的用户个人资料。

etag

string

表示订阅当前状态的实体标记。开发者将为订阅操作提供此 etag。对于自动续订型订阅和预付费订阅,此 etag 始终存在。

outOfAppPurchaseContext

object (OutOfAppPurchaseContext)

与应用外购买有关的其他背景信息。仅当通过 Google Play 订阅中心进行重新订阅购买交易(即在同一产品的上一次订阅到期后进行的订阅购买交易)时,此信息才存在。在您确认订阅后,此字段将被移除。

onHoldStateContext

object (OnHoldStateContext)

可选。有关处于 ON_HOLD 状态的订阅的其他背景信息。仅当订阅当前具有如下 subscriptionState 时才存在:SUBSCRIPTION_STATE_ON_HOLD。

inGracePeriodStateContext

object (InGracePeriodStateContext)

可选。有关处于 IN_GRACE_PERIOD 状态的订阅的其他背景信息。仅当订阅当前具有如下 subscriptionState 时才存在:SUBSCRIPTION_STATE_IN_GRACE_PERIOD。

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 表示法
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "userInitiatedCancellation": {
    object (UserInitiatedCancellation)
  },
  "systemInitiatedCancellation": {
    object (SystemInitiatedCancellation)
  },
  "developerInitiatedCancellation": {
    object (DeveloperInitiatedCancellation)
  },
  "replacementCancellation": {
    object (ReplacementCancellation)
  }
  // End of mutually exclusive fields.
}
字段
订阅取消的原因。以下是互斥字段的列表。在响应中,最多只能设置其中一个字段:
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 指定了该 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,
  "developerTargetedOffers": [
    {
      object (DeveloperTargetedOffer)
    }
  ],
  "latestSuccessfulOrderId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "autoRenewingPlan": {
    object (AutoRenewingPlan)
  },
  "prepaidPlan": {
    object (PrepaidPlan)
  }
  // End of mutually exclusive fields.
  "offerDetails": {
    object (OfferDetails)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "deferredItemReplacement": {
    object (DeferredItemReplacement)
  },
  "deferredItemRemoval": {
    object (DeferredItemRemoval)
  }
  // End of mutually exclusive fields.
  "signupPromotion": {
    object (SignupPromotion)
  },
  "itemReplacement": {
    object (ItemReplacement)
  },
  "offerPhase": {
    object (OfferPhase)
  }
}
字段
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"。

developerTargetedOffers[]

object (DeveloperTargetedOffer)

可选。为此订单项注册的面向开发者的优惠的详细信息。

latestSuccessfulOrderId

string

与此商品关联的最新成功订单的订单 ID。如果用户尚未拥有该商品(例如,被延迟替换的商品),则不存在此字段。

订阅方案类型。以下是互斥字段的列表。在响应中,最多只能设置其中一个字段:
autoRenewingPlan

object (AutoRenewingPlan)

商品采用自动续订型方案。

prepaidPlan

object (PrepaidPlan)

商品采用预付费方案。

互斥字段结束。
offerDetails

object (OfferDetails)

相应商品的优惠详细信息。

当商品具有延迟更改时存在此字段。可以移除或替换延迟商品。以下是互斥字段的列表。在响应中,最多只能设置其中一个字段:
deferredItemReplacement

object (DeferredItemReplacement)

有关延迟商品替换的信息。

deferredItemRemoval

object (DeferredItemRemoval)

有关延迟商品移除的信息。

互斥字段结束。
signupPromotion

object (SignupPromotion)

此商品的促销活动详情。仅当在注册期间应用了促销活动时,才设置此字段。

itemReplacement

object (ItemReplacement)

要替换的商品的详细信息。仅当此商品在之前的订阅中替换了其他商品时,系统才会填充此字段,并且此字段仅在购买时间后的 60 天内可用。

offerPhase

object (OfferPhase)

此商品的当前优惠阶段详情。

AutoRenewingPlan

与自动续订型方案相关的信息。

JSON 表示法
{
  "autoRenewEnabled": boolean,
  "recurringPrice": {
    object (Money)
  },
  "priceChangeDetails": {
    object (SubscriptionItemPriceChangeDetails)
  },
  "installmentDetails": {
    object (InstallmentPlan)
  },
  "planTransitionDetails": {
    object (PlanTransitionDetails)
  },
  "priceStepUpConsentDetails": {
    object (PriceStepUpConsentDetails)
  }
}
字段
autoRenewEnabled

boolean

如果订阅当前设置为自动续订,例如用户尚未取消订阅,则设置此值。

recurringPrice

object (Money)

自动续订型方案的当前周期性价格。请注意,价格不考虑折扣,也不含税费。对于不含税价格,如果需要交易详情,请改为调用 orders.get API。

priceChangeDetails

object (SubscriptionItemPriceChangeDetails)

自订阅注册以来商品的最后一次价格变动的信息。

installmentDetails

object (InstallmentPlan)

自动续订型方案的分期付款方案合约期和状态相关信息。

planTransitionDetails

object (PlanTransitionDetails)

相关联的方案切换的信息。仅当相应方案具有相关联的切换方案时存在,并且将仅包含与商品相关联的最新切换详细信息。

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

此类型没有字段。

它可以指示线上分期付款方案是否正待取消。只有在用户完成所有承诺的付款后,取消才会发生。

PlanTransitionDetails

与方案切换相关的信息。

JSON 表示法
{
  "productId": string,
  "basePlanId": string,
  "offerId": string,
  "transitionInfo": {
    object (TransitionInfo)
  }
}
字段
productId

string

[必填] 相应方案将切换到的产品 ID(例如“monthly001”)。

basePlanId

string

[必填] 相应方案将切换到的基础方案的 ID。

offerId

string

优惠 ID。仅针对折扣优惠存在。仅当目标方案不是基础方案时,系统才会设置此字段。

transitionInfo

object (TransitionInfo)

有关安排的方案切换的其他信息。仅当已安排方案切换时存在。

TransitionInfo

与安排的方案切换相关的信息。

JSON 表示法
{
  "transitionState": enum (TransitionState),
  "price": {
    object (Money)
  },
  "expectedTransitionTime": string
}
字段
transitionState

enum (TransitionState)

仅限输出。[必填] 切换的当前状态。

price

object (Money)

方案将切换到的默认基础方案价格。

expectedTransitionTime

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

TransitionState

切换可能处于的状态。

枚举
TRANSITION_STATE_UNSPECIFIED 未指定切换状态。
SCHEDULED 已安排在未来启动切换。
IN_PROGRESS 已启动切换流程,并且已向用户发送初始切换通知。
COMPLETED 已完成切换。
CANCELED 已取消切换。

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 表示法
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "oneTimeCode": {
    object (OneTimeCode)
  },
  "vanityCode": {
    object (VanityCode)
  }
  // End of mutually exclusive fields.
}
字段
应用于商品的促销类型。以下是互斥字段的列表。在响应中,最多只能设置其中一个字段:
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 更换后,方案将保持不变。

OfferPhase

优惠阶段详情。

JSON 表示法
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "prorationPeriod": {
    object (ProrationPeriodOfferPhase)
  },
  "freeTrial": {
    object (FreeTrialOfferPhase)
  },
  "introductoryPrice": {
    object (IntroductoryPriceOfferPhase)
  },
  "basePrice": {
    object (BasePriceOfferPhase)
  }
  // End of mutually exclusive fields.
}
字段
优惠阶段详情。以下是互斥字段的列表。在响应中,最多只能设置其中一个字段:
prorationPeriod

object (ProrationPeriodOfferPhase)

在优惠阶段为按比例计费期时设置。

freeTrial

object (FreeTrialOfferPhase)

在优惠阶段为免费试用时设置。

introductoryPrice

object (IntroductoryPriceOfferPhase)

在优惠阶段为初次体验价优惠阶段时设置。

basePrice

object (BasePriceOfferPhase)

如果优惠阶段是基础方案定价阶段,则设置此值。

互斥字段结束。

ProrationPeriodOfferPhase

按比例计算期优惠阶段的详细信息。

JSON 表示法
{
  "originalOfferPhaseType": enum (OriginalOfferPhaseType)
}
字段
originalOfferPhaseType

enum (OriginalOfferPhaseType)

按比例计费期之前的原始优惠阶段类型。仅在按比例计算的周期从现有优惠阶段更新时设置。

OriginalOfferPhaseType

如果优惠付款是按比例计算的付款,则为优惠付款的原始优惠阶段。

枚举
ORIGINAL_OFFER_PHASE_TYPE_UNSPECIFIED 未指定原始优惠阶段类型。
BASE 订阅处于基本价格阶段(例如全价)。
INTRODUCTORY 订阅处于初次体验价阶段。
FREE_TRIAL 订阅处于免费试用期。

FreeTrialOfferPhase

此类型没有字段。

有关免费试用优惠阶段的详细信息。

IntroductoryPriceOfferPhase

此类型没有字段。

初次体验价优惠阶段的相关详情。

BasePriceOfferPhase

此类型没有字段。

基本价格优惠阶段的详细信息。

DeveloperTargetedOffer

面向开发者的订阅订单项优惠的相关信息。

JSON 表示法
{
  "offerId": string,
  "activateTime": string
}
字段
offerId

string

可选。开发者创建的订阅优惠 ID。

activateTime

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

OutOfAppPurchaseContext

与应用外购买相关的具体信息。

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

object (ExternalAccountIdentifiers)

此 SKU 的上一个过期订阅的用户账号标识符。

expiredPurchaseToken

string

上次过期的订阅的购买令牌。如果 purchaseToken 与用户之间的关联存储在您的数据库中,则此购买令牌只能用于帮助识别用户。如果订阅已过期超过 60 天,则无法使用此令牌调用 Google Developer API。

OnHoldStateContext

有关处于 ON_HOLD 状态的订阅的其他背景信息。

JSON 表示法
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "renewalDeclined": {
    object (RenewalDeclinedContext)
  }
  // End of mutually exclusive fields.
}
字段
订阅处于 ON_HOLD 状态的原因。以下是互斥字段的列表。在响应中,最多只能设置其中一个字段:
renewalDeclined

object (RenewalDeclinedContext)

可选。续订付款遭拒。

互斥字段结束。

RenewalDeclinedContext

与续订请求被拒场景相关的上下文。

JSON 表示法
{
  "pendingOrderId": string
}
字段
pendingOrderId

string

必需。导致该状态的待处理或失败订单的 ID。

InGracePeriodStateContext

有关处于 IN_GRACE_PERIOD 状态的订阅的其他背景信息。

JSON 表示法
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "renewalDeclined": {
    object (RenewalDeclinedContext)
  }
  // End of mutually exclusive fields.
}
字段
订阅处于 IN_GRACE_PERIOD 状态的原因。以下是互斥字段的列表。在响应中,最多只能设置其中一个字段:
renewalDeclined

object (RenewalDeclinedContext)

可选。续订付款遭拒。

互斥字段结束。

方法

activateoffertargeting

为特定优惠启用定位。

cancel

取消用户购买的订阅。

cancelplantransition

取消为订阅切换方案。

deactivateoffertargeting

停用特定优惠的目标对象。

defer

推迟订阅续订。

get

获取关于订阅的元数据

revoke

撤销用户购买的订阅。

scheduleplantransition

为订阅安排方案切换。

错误代码

此资源相关操作将返回以下 HTTP 错误代码:

错误代码 原因 说明 分辨率
400 / 410 subscriptionExpired 订阅已过期,无法执行请求的操作。 检查订阅的到期时间。无法对已失效订阅执行此操作。
400 subscriptionInvalidArgument 订阅请求中提供的参数无效。 请查看 API 文档,确保所有必填字段均已提供且格式正确。
400 invalidPurchaseState 购买交易不处于有效状态,无法执行所请求的操作。例如,您可能正在尝试确认已消耗的购买交易,或取消未处于有效状态的订阅。 在尝试执行操作之前,请使用相应的 Get API 检查资源的当前状态。确保资源处于适合执行该操作的状态。
400 invalidValue 请求中提供的值无效。如果购买令牌格式不正确或无效,通常会返回此错误。 根据 API 参考文档,更正请求正文或参数中的无效字段值。
400 prepaidSubscriptionNotSupported 预付费订阅不支持所请求的操作。 确保操作适用于订阅类型。此错误仅与 Cancel 等方法有关。
400 productNotOwnedByUser 提供的购买令牌有效,但用户目前并未拥有该商品。如果购买交易在确认之前被退款、撤销或过期,就可能会发生这种情况。 在尝试执行操作之前,请使用相应的 Get API 检查资源的当前状态。确保资源处于适合执行该操作的状态。
400 purchaseTokenMismatch 提供的购买令牌与购买交易、软件包名称、订阅 ID 或商品 ID 不匹配。 验证请求中的所有详细信息是否正确且相互对应。
400 required 请求中缺少必填字段或参数。 请查阅 API 文档,确保包含所有必填字段和参数。
400 unsupportedIabType 指定的应用内购结算类型不支持此操作。 确保 API 方法与所管理的商品种类兼容。
403 userInsufficientPermission 用户没有足够的权限来执行请求的操作。 确保经过身份验证的用户在 Google Play 管理中心内拥有必要的权限。如需了解详情,请参阅使用服务账号。
404 notFound 找不到所请求的资源。 验证标识符(例如购买令牌、软件包名称、商品 ID、订阅 ID)是否正确。
409 concurrentUpdate 尝试更新正在同时更新的对象。 使用指数退避算法重试请求。避免同时修改同一资源。
410 purchaseTokenNoLongerValid 购买令牌已永久失效,因为关联的用户账号已被删除或购买记录已不存在。 停止使用此购买令牌。
410 subscriptionNoLongerAvailable 订阅购买交易已过期太久,无法再查询。 此错误表示订阅已过期超过 60 天。您不应再查询这些订阅。
5xx Generic error Google Play 服务器中出现一般性错误。 请重试您的请求。

如果问题仍然存在,请与您的 Google Play 客户经理联系,或提交支持请求。建议您查看 Play 状态信息中心,了解是否存在任何已知服务中断。