更改用户订阅的计费状态Change the billing state of a subscription for a user

在 Microsoft Store 购买 API 中使用此方法来更改给定用户订阅加载项的计费状态。Use this method in the Microsoft Store purchase API to change the billing state of a subscription add-on for a given user. 你可以取消、延长、退款或禁用订阅的自动续订。You can cancel, extend, refund, or disable automatic renewal for a subscription.

备注

此方法仅供已由 Microsoft 预配能够为通用 Windows 平台 (UWP) 应用创建订阅加载项的开发人员帐户使用。This method can only be used by developer accounts that have been provisioned by Microsoft to be able to create subscription add-ons for Universal Windows Platform (UWP) apps. 对于大多数开发人员帐户来说,订阅加载项目前尚不可用。Subscription add-ons are currently not available to most developer accounts.

必备条件Prerequisites

若要使用此方法,你需要:To use this method, you will need:

  • 受众 URI 值为 https://onestore.microsoft.com 的 Azure AD 访问令牌。An Azure AD access token that has the audience URI value https://onestore.microsoft.com.
  • Microsoft Store ID 键代表具有想要更改的订阅权利的用户身份。A Microsoft Store ID key that represents the identity of the user who has an entitlement to the subscription you want to change.

有关详细信息,请参阅管理来自服务的产品授权For more information, see Manage product entitlements from a service.

请求Request

请求语法Request syntax

方法Method 请求 URIRequest URI
POSTPOST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

请求头Request header

标头Header 在任务栏的搜索框中键入Type 描述Description
授权Authorization 字符串string 必需。Required. Azure AD 访问令牌的格式为 Bearer token<>。The Azure AD access token in the form Bearer <token>.
主机Host 字符串string 必须设置为值 purchase.mp.microsoft.comMust be set to the value purchase.mp.microsoft.com.
内容长度Content-Length 数字number 请求正文的长度。The length of the request body.
内容类型Content-Type 字符串string 指定请求和响应类型。Specifies the request and response type. 当前,唯一受支持的值为 application/jsonCurrently, the only supported value is application/json.

请求参数Request parameters

名称Name 在任务栏的搜索框中键入Type 描述Description 必需Required
recurrenceIdrecurrenceId 字符串string 想要更改的订阅 ID。The ID of the subscription you want to change. 若要获取此 ID,请调用获取用户的订阅方法中,标识表示你想要更改,请订阅外接程序的响应正文条目,并使用的值id字段的项。To get this ID, call the get subscriptions for a user method, identify the response body entry that represents the subscription add-on you want to change, and use the value of the id field for the entry. Yes

请求正文Request body

字段Field 在任务栏的搜索框中键入Type 描述Description 必需Required
b2bKeyb2bKey 字符串string 代表想要更改其订阅的用户身份的 Microsoft Store ID 密钥The Microsoft Store ID key that represents the identity of the user whose subscription you want to change. Yes
changeTypechangeType 字符串string 用于标识想要进行的更改类型的以下字符串之一:One of the following strings that identifies the type of change you want to make:
  • 取消:取消的订阅。Cancel: Cancels the subscription.
  • 扩展:扩展了订阅。Extend: Extends the subscription. 如果指定此值,则你必须还包括 extensionTimeInDays 参数。If you specify this value, you must also include the extensionTimeInDays parameter.
  • 退款:向客户退款订阅。Refund: Refunds the subscription to the customer.
  • ToggleAutoRenew:禁用自动续订的订阅。ToggleAutoRenew: Disables automatic renewal for the subscription. 如果当前已禁用订阅的自动续订,则此值不起作用。If automatic renewal is currently disabled for the subscription, this value does nothing.
Yes
extensionTimeInDaysextensionTimeInDays 字符串string 如果 changeType 参数的值为 Extend,则此参数用于指定订阅的延长天数。If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. 是,如果 changeType 的值为 Extend;否则,为否。Yes, if changeType has the value Extend; otherwise, no.

请求示例Request example

以下示例展示了如何使用此方法将订阅期延长 5 天。The following example demonstrates how to use this method to extend the subscription period by 5 days. b2bKey 值替换为代表想要更改其订阅的用户身份的 Microsoft Store ID 密钥Replace the b2bKey value with the Microsoft Store ID key that represents the identity of the user whose subscription you want to change.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

响应Response

此方法将会返回包含与已修改的订阅加载项(包括已修改的任何字段)相关信息的 JSON 响应正文。This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. 下面的示例展示了此方法的响应正文。The following example demonstrates a response body for this method.

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-16T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-10T21:08:13.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

响应正文Response body

响应正文包含以下数据。The response body contains the following data.

Value 在任务栏的搜索框中键入Type 描述Description
autoRenewautoRenew 布尔Boolean 表示是否已将订阅配置为在当前订阅期结束时自动续订。Indicates whether the subscription is configured to automatically renew at the end of the current subscription period.
受益人beneficiary 字符串string 与此订阅关联的权利受益人的 ID。The ID of the beneficiary of the entitlement that is associated with this subscription.
expirationTimeexpirationTime 字符串string 订阅截止日期和时间(ISO 8601 格式)。The date and time the subscription will expire, in ISO 8601 format. 仅当订阅处于特定状态时,此字段才可用。This field is only available when the subscription is in certain states. 截止时间通常表示当前状态截止的时间。The expiration time usually indicates when the current state expires. 例如,对于活动的订阅,截止日期表示下一次自动续订发生的时间。For example, for an active subscription, the expiration date indicates when the next automatic renewal will occur.
expirationTimeWithGraceexpirationTimeWithGrace 字符串string 日期和时间的订阅将过期宽限期内,包括采用 ISO 8601 格式。The date and time the subscription will expire including the grace period, in ISO 8601 format. 此值指示时,用户将失去访问权限的订阅后订阅无法自动续订。This value indicates when the user will lose access to the subscription after the subscription has failed to automatically renew.
idid 字符串string 订阅 ID。The ID of the subscription. 使用此方法表示在你调用更改用户订阅的计费状态方法时想要修改的订阅。Use this value to indicate which subscription you want to modify when you call the change the billing state of a subscription for a user method.
isTrialisTrial 布尔Boolean 表示订阅是否为试用版。Indicates whether the subscription is a trial.
lastModifiedlastModified 字符串string 上次修改订阅的日期和时间(ISO 8601 格式)。The date and time the subscription was last modified, in ISO 8601 format.
marketmarket 字符串string 用户在其中获取订阅的国家/地区代码(两个字母 ISO 3166-1 alpha-2 格式)。The country code (in two-letter ISO 3166-1 alpha-2 format) in which the user acquired the subscription.
productIdproductId 字符串string 表示 Microsoft Store 目录中的订阅加载项的产品Store IDThe Store ID for the product that represents the subscription add-on in the Microsoft Store catalog. 产品的示例应用商店 ID 为 9NBLGGH42CFD。An example Store ID for a product is 9NBLGGH42CFD.
skuIdskuId 字符串string 表示 Microsoft Store 目录中的订阅加载项的 SKUStore IDThe Store ID for the SKU that represents the subscription add-on the Microsoft Store catalog. SKU 的示例应用商店 ID 为 0010。An example Store ID for a SKU is 0010.
startTimestartTime 字符串string 订阅的开始日期和时间(ISO 8601 格式)。The start date and time for the subscription, in ISO 8601 format.
recurrenceStaterecurrenceState 字符串string 以下值之一:One of the following values:
  • None:  这表示永久订阅。None:  This indicates a perpetual subscription.
  • Active:  订阅有效且用户有权使用服务。Active:  The subscription is active and the user is entitled to use the services.
  • Inactive:  订阅已过期,并且用户已关闭订阅的自动续订选项。Inactive:  The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription.
  • Canceled:  订阅已在截止日期之前被故意终止,提供或不提供退款。Canceled:  The subscription has been purposefully terminated before the expiration date, with or without a refund.
  • InDunning:  订阅正处于催缴状态(即,订阅即将过期,且 Microsoft 正尝试获取款项以自动续订此订阅)。InDunning:  The subscription is in dunning (that is, the subscription is nearing expiration, and Microsoft is trying to acquire funds to automatically renew the subscription).
  • Failed:  催缴期已结束,并且在多次尝试后仍无法续订此订阅。Failed:  The dunning period is over and the subscription failed to renew after several attempts.

注意:Note:

  • Inactive/Canceled/Failed 为终端状态。Inactive/Canceled/Failed are terminal states. 当订阅处于这些状态之一时,用户必须重新购买订阅才能再次激活订阅。When a subscription enters one of these states, the user must repurchase the subscription to activate it again. 在这些状态下,用户无权使用服务。The user is not entitled to use the services in these states.
  • 当订阅处于 Canceled 状态时,expirationTime 将会更新为取消的日期和时间。When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
  • 在整个生命周期中,订阅 ID 将保持相同。The ID of the subscription will remain the same during its entire lifetime. 打开或关闭自动续订选项并不会更改订阅 ID。It will not change if the auto-renew option is turned on or off. 如果用户在达到终端状态之后重新购买了订阅,则会创建新的订阅 ID。If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
  • 订阅 ID 可用于在单个订阅上执行任何操作。The ID of a subscription should be used to execute any operation on an individual subscription.
  • 当用户在取消或中断订阅之后重新购买了订阅时,如果查询该用户的结果,则你将会获得两个条目:一个处于终端状态的旧订阅 ID 和一个处于活动状态的新订阅 ID。When a user repurchases a subscription after cancelling or discontinuing it, if you query the results for the user you will get two entries: one with the old subscription ID in a terminal state, and one with the new subscription ID in an active state.
  • 最好始终检查 recurrenceState 和 expirationTime,因为更新至 recurrenceState 可能会延迟几分钟(有时候会是几小时)。It's always a good practice to check both recurrenceState and expirationTime, since updates to recurrenceState can potentially be delayed by a few minutes (or occasionally hours).
cancellationDatecancellationDate 字符串string 用户订阅取消的日期和时间(ISO 8601 格式)。The date and time the user's subscription was cancelled, in ISO 8601 format.