更改用户订阅的计费状态

  • 项目

在 Microsoft Store 购买 API 中使用此方法来更改给定用户订阅加载项的计费状态。 你可以取消、延长、退款或禁用订阅的自动续订。

注意

此方法仅供已由 Microsoft 预配能够为通用 Windows 平台 (UWP) 应用创建订阅加载项的开发人员帐户使用。 对于大多数开发人员帐户来说，订阅加载项目前尚不可用。

Microsoft.StoreServices 库通过 StoreServicesClient.RecurrenceChangeAysnc API 提供此方法的功能。

先决条件

若要使用此方法，你需要：

  • 受众 URI 值为 https://onestore.microsoft.com 的 Azure AD 访问令牌。
  • Microsoft Store ID 键代表具有想要更改的订阅权利的用户身份。

有关详细信息，请参阅管理来自服务的产品授权。

请求

请求语法

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

请求头

标头 类型 说明
授权 字符串 必需。 Azure AD 访问令牌的格式为 Bearertoken<>。
主机 string 必须设置为值 purchase.mp.microsoft.com。
Content-Length 数值 请求正文的长度。
Content-Type 字符串 指定请求和响应类型。 当前，唯一受支持的值为 application/json。

请求参数

名称 类型 说明 必须
recurrenceId string 想要更改的订阅 ID。 若要获得此 ID，请调用获取用户订阅方法，标识代表想要更改的订阅加载项的响应正文条目并使用该条目的 id 字段值。 是

请求正文

字段 类型 说明 必须
b2bKey string 代表想要更改其订阅的用户身份的 Microsoft Store ID 密钥。 是
changeType string 用于标识想要进行的更改类型的以下字符串之一：
  • Cancel：取消订阅。
  • Extend：延长订阅。 如果指定此值，则你必须还包括 extensionTimeInDays 参数。
  • Refund：将订阅款项退还给客户。
  • ToggleAutoRenew：禁用订阅的自动续订。 如果当前已禁用订阅的自动续订，则此值不起作用。
 是
extensionTimeInDays string 如果 changeType 参数的值为 Extend，则此参数用于指定订阅的延长天数。 是，如果 changeType 的值为 Extend；否则，为否。

请求示例

以下示例展示了如何使用此方法将订阅期延长 5 天。 将 b2bKey 值替换为代表想要更改其订阅的用户身份的 Microsoft Store ID 密钥。

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

响应

此方法将会返回包含与已修改的订阅加载项（包括已修改的任何字段）相关信息的 JSON 响应正文。 下面的示例展示了此方法的响应正文。

{
  "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"
    }
  ]
}

响应正文

响应正文包含以下数据。

Value 类型 说明
autoRenew 布尔 表示是否已将订阅配置为在当前订阅期结束时自动续订。
受益人 string 与此订阅关联的权利受益人的 ID。
expirationTime string 订阅截止日期和时间（ISO 8601 格式）。 仅当订阅处于特定状态时，此字段才可用。 截止时间通常表示当前状态截止的时间。 例如，对于活动的订阅，截止日期表示下一次自动续订发生的时间。
expirationTimeWithGrace string 订阅到期的日期和时间，包括宽限期（采用 ISO 8601 格式）。 此值指示订阅未能自动续订后用户何时将失去订阅的访问权限。
id string 订阅 ID。 使用此方法表示在你调用更改用户订阅的计费状态方法时想要修改的订阅。
isTrial 布尔 表示订阅是否为试用版。
lastModified string 上次修改订阅的日期和时间（ISO 8601 格式）。
market string 用户在其中获取订阅的国家/地区代码（两个字母 ISO 3166-1 alpha-2 格式）。
productId string 表示 Microsoft Store 目录中的订阅加载项的产品的 Store ID。 产品的示例应用商店 ID 为 9NBLGGH42CFD。
skuId string 表示 Microsoft Store 目录中的订阅加载项的 SKU 的 Store ID。 SKU 的示例应用商店 ID 为 0010。
startTime string 订阅的开始日期和时间（ISO 8601 格式）。
recurrenceState string 以下值之一：
  • None：这指示永久订阅。
  • Active：订阅有效且用户有权使用服务。
  • Inactive：订阅已过期，并且用户已关闭订阅的自动续订选项。
  • Canceled：订阅已在截止日期之前被故意终止，提供或不提供退款。
  • InDunning：订阅正处于“催缴”状态（即，订阅即将过期，且 Microsoft 正尝试获取款项以自动续订此订阅）。
  • Failed：催缴期已结束，并且在多次尝试后仍无法续订此订阅。

注意：

  • Inactive/Canceled/Failed 为终端状态。 当订阅处于这些状态之一时，用户必须重新购买订阅才能再次激活订阅。 在这些状态下，用户无权使用服务。
  • 当订阅处于 Canceled 状态时，expirationTime 将会更新为取消的日期和时间。
  • 在整个生命周期中，订阅 ID 将保持相同。 打开或关闭自动续订选项并不会更改订阅 ID。 如果用户在达到终端状态之后重新购买了订阅，则会创建新的订阅 ID。
  • 订阅 ID 可用于在单个订阅上执行任何操作。
  • 当用户在取消或中断订阅之后重新购买了订阅时，如果查询该用户的结果，则你将会获得两个条目：一个处于终端状态的旧订阅 ID 和一个处于活动状态的新订阅 ID。
  • 最好始终检查 recurrenceState 和 expirationTime，因为更新至 recurrenceState 可能会延迟几分钟（有时候会是几小时）。
cancellationDate string 用户订阅取消的日期和时间（ISO 8601 格式）。