此页面由 Cloud Translation API 翻译。

REST Resource: monetization.subscriptions

资源：订阅

应用的单项订阅。

JSON 表示法

JSON 表示法
{ "packageName": string, "productId": string, "basePlans": [ { object (`BasePlan`) } ], "listings": [ { object (`SubscriptionListing`) } ], "archived": boolean, "taxAndComplianceSettings": { object (`SubscriptionTaxAndComplianceSettings`) }, "restrictedPaymentCountries": { object (`RestrictedPaymentCountries`) } }

{
  "packageName": string,
  "productId": string,
  "basePlans": [
    {
      object (BasePlan)
    }
  ],
  "listings": [
    {
      object (SubscriptionListing)
    }
  ],
  "archived": boolean,
  "taxAndComplianceSettings": {
    object (SubscriptionTaxAndComplianceSettings)
  },
  "restrictedPaymentCountries": {
    object (RestrictedPaymentCountries)
  }
}

字段
`packageName`	`string` 不可变。父级应用的软件包名称。
`productId`	`string` 不可变。商品的唯一商品 ID。在父级应用内具有唯一性。商品 ID 必须由以下字符组成：小写字母 (a-z)、数字 (0-9)、下划线 (_) 和句点 (.)。此外，商品 ID 必须以小写字母或数字开头，长度介于 1 和 40 个字符之间（含边界值）。
`basePlans[]`	`object (BasePlan)` 相应订阅的基础方案集。表示在不应用任何其他优惠的情况下订阅的价格和时长。
`listings[]`	`object (SubscriptionListing)` 必需。相应订阅的本地化商品详情列表。必须至少包含一个与父级应用的默认语言对应的条目。
`archived (deprecated)`	`boolean` 此项已弃用！仅限输出。已弃用：不支持订阅归档。
`taxAndComplianceSettings`	`object (SubscriptionTaxAndComplianceSettings)` 有关税费和法规遵从方面的详细信息。
`restrictedPaymentCountries`	`object (RestrictedPaymentCountries)` 可选。在相应国家/地区，必须使用在本国家/地区注册的支付方式来购买相应订阅。如果为空，则表示未施加任何支付地点限制。

BasePlan

订阅的单个基础方案。

JSON 表示法

JSON 表示法
{ "basePlanId": string, "state": enum (`State`), "regionalConfigs": [ { object (`RegionalBasePlanConfig`) } ], "offerTags": [ { object (`OfferTag`) } ], "otherRegionsConfig": { object (`OtherRegionsBasePlanConfig`) }, // Union field `base_plan_type` can be only one of the following: "autoRenewingBasePlanType": { object (`AutoRenewingBasePlanType`) }, "prepaidBasePlanType": { object (`PrepaidBasePlanType`) }, "installmentsBasePlanType": { object (`InstallmentsBasePlanType`) } // End of list of possible types for union field `base_plan_type`. }

{
  "basePlanId": string,
  "state": enum (State),
  "regionalConfigs": [
    {
      object (RegionalBasePlanConfig)
    }
  ],
  "offerTags": [
    {
      object (OfferTag)
    }
  ],
  "otherRegionsConfig": {
    object (OtherRegionsBasePlanConfig)
  },

  // Union field base_plan_type can be only one of the following:
  "autoRenewingBasePlanType": {
    object (AutoRenewingBasePlanType)
  },
  "prepaidBasePlanType": {
    object (PrepaidBasePlanType)
  },
  "installmentsBasePlanType": {
    object (InstallmentsBasePlanType)
  }
  // End of list of possible types for union field base_plan_type.
}

字段
`basePlanId`	`string` 必需。不可变。相应基础方案的唯一标识符。在订阅中必须具有唯一性，且必须符合 RFC-1034。也就是说，相应 ID 只能包含小写字母 (a-z)、数字 (0-9) 和连字符 (-)，并且长度不得超过 63 个字符。
`state`	`enum (State)` 仅限输出。基础方案的状态，即是否有效。草稿和无效基础方案可以被激活或删除。有效基础方案可以设为无效。无效基础方案可以取消。无法通过更新资源来更改此字段。请改为使用专用端点。
`regionalConfigs[]`	`object (RegionalBasePlanConfig)` 相应基础方案在特定地区的专有信息。
`offerTags[]`	`object (OfferTag)` 为相应基础方案指定、通过结算库返回到应用的自定义标记的列表（最多 20 个自定义标记）。相应基础方案的订阅优惠也将通过结算库收到这些优惠标记。
`otherRegionsConfig`	`object (OtherRegionsBasePlanConfig)` Google Play 未来可能新增的任何地区所适用的定价信息。如果省略，将不会在 Google Play 未来可能新增的任何地区自动提供基础方案。
联合字段 `base_plan_type`。相应基础方案的类型。只能设置一个值。基础方案创建后，基础方案类型便无法更改。`base_plan_type` 只能是下列其中一项：
`autoRenewingBasePlanType`	`object (AutoRenewingBasePlanType)` 如果基础方案会定期自动续订，则设置此值。
`prepaidBasePlanType`	`object (PrepaidBasePlanType)` 如果基础方案不会在结算周期结束时自动续订，则设置此值。
`installmentsBasePlanType`	`object (InstallmentsBasePlanType)` 如果基础方案采用分期付款方式，由用户承诺按指定期数付款，则设置此值。

州

基础方案的当前状态。

枚举
`STATE_UNSPECIFIED`	未指定状态。
`DRAFT`	基础方案当前处于草稿状态，尚未激活。此时可以将其删除，不会引发任何问题。
`ACTIVE`	基础方案处于有效状态，可供新订阅者使用。
`INACTIVE`	基础方案处于无效状态，仅可供现有订阅者使用。

AutoRenewingBasePlanType

表示会在订阅期结束时自动续订的基础方案。

JSON 表示法

JSON 表示法
{ "billingPeriodDuration": string, "gracePeriodDuration": string, "accountHoldDuration": string, "resubscribeState": enum (`ResubscribeState`), "prorationMode": enum (`SubscriptionProrationMode`), "legacyCompatible": boolean, "legacyCompatibleSubscriptionOfferId": string }

{
  "billingPeriodDuration": string,
  "gracePeriodDuration": string,
  "accountHoldDuration": string,
  "resubscribeState": enum (ResubscribeState),
  "prorationMode": enum (SubscriptionProrationMode),
  "legacyCompatible": boolean,
  "legacyCompatibleSubscriptionOfferId": string
}

字段
`billingPeriodDuration`	`string` 必需。不可变。订阅期限，采用 ISO 8601 格式指定。如需获取可接受的结算周期的列表，请参阅帮助中心。基本方案创建后，时长便无法更改。
`gracePeriodDuration`	`string` 订阅宽限期，采用 ISO 8601 格式指定。可接受的值必须以天为单位，且必须介于 P0D 和 30D 与基础方案结算周期的较小者之间。如果未指定，将根据结算周期使用默认值。 gracePeriodDuration 和 accountHoldDuration 的总和必须介于 P30D 和 P60D 天之间（含）。
`accountHoldDuration`	`string` 可选。订阅的自定义账号冻结期，采用 ISO 8601 格式指定。可接受的值必须以天为单位，且必须介于 P0D 和 P60D 之间。空字段表示建议的账号保留期，计算方式为 60 天减去宽限期。 gracePeriodDuration 和 accountHoldDuration 的总和必须介于 P30D 和 P60D 天之间（含）。
`resubscribeState`	`enum (ResubscribeState)` 用于表示用户是否应该能够在 Google Play 途径中重新订阅相应基础方案。如果未指定，则默认为 RESUBSCRIBE_STATE_ACTIVE。
`prorationMode`	`enum (SubscriptionProrationMode)` 基础方案的按比例计费模式决定了当用户从其他基础方案切换到相应方案时会出现什么情况。如果未指定，则默认为 CHARGE_ON_NEXT_BILLING_DATE。
`legacyCompatible`	`boolean` 用于表示续订型基础方案是否向后兼容。向后兼容的基础方案由 Google Play 结算库已弃用的 querySkuDetailsAsync() 方法返回。对于指定订阅，只有一个续订型基础方案可以标记为与旧版兼容。
`legacyCompatibleSubscriptionOfferId`	`string` 与旧版兼容的订阅优惠 ID。向后兼容的订阅优惠由 Google Play 结算库已弃用的 querySkuDetailsAsync() 方法返回。对于指定续订型基础方案，只有一个订阅优惠可以标记为与旧版兼容。如要让任何订阅优惠均不与旧版兼容，请将此字段设置为空字符串。

ResubscribeState

基础方案重新订阅状态。

枚举
`RESUBSCRIBE_STATE_UNSPECIFIED`	未指定状态。
`RESUBSCRIBE_STATE_ACTIVE`	重新订阅处于有效状态。
`RESUBSCRIBE_STATE_INACTIVE`	重新订阅处于无效状态。

SubscriptionProrationMode

用于续订型基础方案的按比例计费模式。

枚举
`SUBSCRIPTION_PRORATION_MODE_UNSPECIFIED`	未指定模式。
`SUBSCRIPTION_PRORATION_MODE_CHARGE_ON_NEXT_BILLING_DATE`	系统将在用户当前的结算周期结束时，针对用户的新基础方案进行扣款。
`SUBSCRIPTION_PRORATION_MODE_CHARGE_FULL_PRICE_IMMEDIATELY`	系统将立即针对用户的新基础方案进行全额扣款。用户现有订阅的任何剩余期限会累加到新结算方案的时长中。

PrepaidBasePlanType

表示不会在结束时自动续订、必须由用户手动续订的基础方案。

JSON 表示法
{ "billingPeriodDuration": string, "timeExtension": enum (`TimeExtension`) }

字段

billingPeriodDuration

string

必需。不可变。订阅期限，采用 ISO 8601 格式指定。如需获取可接受的结算周期的列表，请参阅帮助中心。基本方案创建后，时长便无法更改。

timeExtension

enum (TimeExtension)

用于表示用户是否应该能够在 Google Play 途径中为相应预付费基础方案延期。如果未指定，则默认为 TIME_EXTENSION_ACTIVE。

TimeExtension

基础方案延期。

枚举
`TIME_EXTENSION_UNSPECIFIED`	未指定状态。
`TIME_EXTENSION_ACTIVE`	延期处于有效状态。用户可以充值或将其预付费方案延期。
`TIME_EXTENSION_INACTIVE`	延期处于无效状态。用户无法充值或为其预付费方案延期。

InstallmentsBasePlanType

表示用户承诺按指定期数付款的分期付款型基础方案。

JSON 表示法

JSON 表示法
{ "billingPeriodDuration": string, "committedPaymentsCount": integer, "renewalType": enum (`RenewalType`), "gracePeriodDuration": string, "accountHoldDuration": string, "resubscribeState": enum (`ResubscribeState`), "prorationMode": enum (`SubscriptionProrationMode`) }

{
  "billingPeriodDuration": string,
  "committedPaymentsCount": integer,
  "renewalType": enum (RenewalType),
  "gracePeriodDuration": string,
  "accountHoldDuration": string,
  "resubscribeState": enum (ResubscribeState),
  "prorationMode": enum (SubscriptionProrationMode)
}

字段
`billingPeriodDuration`	`string` 必需。不可变。订阅期限，采用 ISO 8601 格式指定。如需获取可接受的结算周期的列表，请参阅帮助中心。基本方案创建后，时长便无法更改。
`committedPaymentsCount`	`integer` 必需。不可变。用户承诺的付款期数。基本方案创建后，此属性便无法更改。
`renewalType`	`enum (RenewalType)` 必需。不可变。分期付款型基础方案续订类型。决定了初始合约期结束时的行为。基础方案创建后，续订类型便无法更改。
`gracePeriodDuration`	`string` 订阅宽限期，采用 ISO 8601 格式指定。可接受的值必须以天为单位，且必须介于 P0D 和 30D 与基础方案结算周期的较小者之间。如果未指定，将根据结算周期使用默认值。 gracePeriodDuration 和 accountHoldDuration 的总和必须介于 P30D 和 P60D 天之间（含）。
`accountHoldDuration`	`string` 可选。订阅的自定义账号冻结期，采用 ISO 8601 格式指定。可接受的值必须以天为单位，且必须介于 P0D 和 P60D 之间。空字段表示建议的账号保留期，计算方式为 60 天减去宽限期。 gracePeriodDuration 和 accountHoldDuration 的总和必须介于 P30D 和 P60D 天之间（含）。
`resubscribeState`	`enum (ResubscribeState)` 用于表示用户是否应该能够在 Google Play 途径中重新订阅相应基础方案。如果未指定，则默认为 RESUBSCRIBE_STATE_ACTIVE。
`prorationMode`	`enum (SubscriptionProrationMode)` 基础方案的按比例计费模式决定了当用户从其他基础方案切换到相应方案时会出现什么情况。如果未指定，则默认为 CHARGE_ON_NEXT_BILLING_DATE。

RenewalType

分期付款型基础方案续订类型。决定了初始合约期结束时的行为。基础方案创建后，续订类型便无法更改。

枚举
`RENEWAL_TYPE_UNSPECIFIED`	未指定状态。
`RENEWAL_TYPE_RENEWS_WITHOUT_COMMITMENT`	按结算周期时长定期续订，无合约期。
`RENEWAL_TYPE_RENEWS_WITH_COMMITMENT`	在有合约期的情况下续订，时长与初始合约期相同。

RegionalBasePlanConfig

针对特定地区的专用基础方案的配置。

JSON 表示法
{ "regionCode": string, "newSubscriberAvailability": boolean, "price": { object (`Money`) } }

字段

字段
`regionCode`	`string` 必需。相应配置适用地区的地区代码（按照 ISO 3166-2 的定义），例如“US”。
`newSubscriberAvailability`	`boolean` 用于表示指定地区的基础方案是否可供新订阅者使用。如果此值设置为 false，系统不会取消现有订阅者的订阅。如果未指定，则默认为 false。
`price`	`object (Money)` 指定地区的基础方案的价格。如果基础方案可供新订阅者使用，则必须设置。必须以与指定地区相关联的币种设置。

regionCode

string

必需。相应配置适用地区的地区代码（按照 ISO 3166-2 的定义），例如“US”。

newSubscriberAvailability

boolean

用于表示指定地区的基础方案是否可供新订阅者使用。如果此值设置为 false，系统不会取消现有订阅者的订阅。如果未指定，则默认为 false。

price

object (Money)

指定地区的基础方案的价格。如果基础方案可供新订阅者使用，则必须设置。必须以与指定地区相关联的币种设置。

OtherRegionsBasePlanConfig

Google Play 可能新增的任何地区所适用的定价信息。

JSON 表示法
{ "usdPrice": { object (`Money`) }, "eurPrice": { object (`Money`) }, "newSubscriberAvailability": boolean }

字段

字段
`usdPrice`	`object (Money)` 必需。要在 Google Play 可能新增的任何地区使用的价格（美元）。
`eurPrice`	`object (Money)` 必需。要在 Google Play 可能新增的任何地区使用的价格（欧元）。
`newSubscriberAvailability`	`boolean` 用于表示在 Google Play 可能新增的任何地区，基础方案是否可供新订阅者使用。如果未指定，则默认为 false。

usdPrice

object (Money)

必需。要在 Google Play 可能新增的任何地区使用的价格（美元）。

eurPrice

object (Money)

必需。要在 Google Play 可能新增的任何地区使用的价格（欧元）。

newSubscriberAvailability

boolean

用于表示在 Google Play 可能新增的任何地区，基础方案是否可供新订阅者使用。如果未指定，则默认为 false。

SubscriptionListing

消费者可见的订阅元数据。

JSON 表示法
{ "languageCode": string, "title": string, "benefits": [ string ], "description": string }

字段
`languageCode`	`string` 必需。相应商品详情的语言（按照 BCP-47 的定义），例如“en-US”。
`title`	`string` 必需。相应订阅的名称（采用相应商品详情所用的语言）。纯文本。
`benefits[]`	`string` 在 Play 商店等平台和恢复流程中向用户显示的福利列表（采用相应商品详情所用的语言）。纯文本。包含最多四项福利的有序列表。
`description`	`string` 相应订阅的说明（采用相应商品详情所用的语言）。长度上限：80 个字符。纯文本。

方法
`archive (deprecated)`	已弃用：不支持订阅归档。
`batchGet`	读取一项或多项订阅。
`batchUpdate`	批量更新订阅。
`create`	创建新订阅。
`delete`	删除订阅。
`get`	读取一项订阅。
`list`	列出指定应用下的全部订阅。
`patch`	更新现有订阅。

错误代码

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

错误代码	原因	说明	分辨率
`400`	`invalidValue`	请求中提供的值无效。如果购买令牌格式有误或无效，系统通常会返回此错误。	根据 API 参考文档，更正请求正文或参数中的无效字段值。
`400`	`required`	请求中缺少必需的字段或参数。	请参阅 API 文档，确保包含所有必填字段和参数。
`403`	`userInsufficientPermission`	用户没有足够的权限来执行所请求的操作。	确保经过身份验证的用户在 Google Play 管理中心内拥有必要的权限。如需了解详情，请参阅使用服务账号。
`404`	`notFound`	找不到所请求的资源。	验证标识符（例如购买令牌、软件包名称、商品 ID、订阅 ID）是否正确。
`409`	`concurrentUpdate`	尝试更新正在并发更新的对象。	使用指数退避算法重试请求。避免同时修改同一资源。
`5xx`	`Generic error`	Google Play 服务器中的一般错误。	请重试您的请求。如果问题仍然存在，请与您的 Google Play 客户经理联系，或提交支持请求。不妨查看 Play 状态信息中心，了解是否存在任何已知的服务中断。

REST Resource: monetization.subscriptions

资源：订阅

BasePlan

州

AutoRenewingBasePlanType

ResubscribeState

SubscriptionProrationMode

PrepaidBasePlanType

TimeExtension

InstallmentsBasePlanType

RenewalType

RegionalBasePlanConfig

OtherRegionsBasePlanConfig

SubscriptionListing

方法

`archive (deprecated)`

`batchGet`

`batchUpdate`

`create`

`delete`

`get`

`list`

`patch`

错误代码

REST Resource: monetization.subscriptions 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

资源：订阅

BasePlan

州

AutoRenewingBasePlanType

ResubscribeState

SubscriptionProrationMode

PrepaidBasePlanType

TimeExtension

InstallmentsBasePlanType

RenewalType

RegionalBasePlanConfig

OtherRegionsBasePlanConfig

SubscriptionListing

方法

archive (deprecated)

batchGet

batchUpdate

create

delete

get

list

patch

错误代码

REST Resource: monetization.subscriptions

`archive (deprecated)`

`batchGet`

`batchUpdate`

`create`

`delete`

`get`

`list`

`patch`