更改用户的订阅的计费状态

2025-06-10

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

注释

此方法只能由Microsoft预配的开发人员帐户使用，以便为通用 Windows 平台（UWP）应用创建订阅加载项。目前，订阅附加组件对大多数开发人员帐户不可用。

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

先决条件

若要使用此方法，需要：

具有受众 URI 值为 https://onestore.microsoft.com的 Azure AD 访问令牌。
Microsoft Store ID 密钥，表示拥有权利访问您要更改的订阅的用户身份。

有关详细信息，请参阅在服务中管理产品权限。

请求

请求语法

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

请求标头

标题	类型	DESCRIPTION
授权	字符串	必填。 Azure AD 访问令牌，形式为Bearer<token>。
主机	字符串	必须设置为值 purchase.mp.microsoft.com。
内容长度	数字	请求正文的长度。
内容类型（Content-Type）	字符串	指定请求和响应类型。目前，唯一支持的值是 application/json。

请求参数

名称	类型	DESCRIPTION	必选
重复ID	字符串	要更改的订阅的 ID。若要获取此 ID，请调用获取用户订阅的方法，找出表示您想更改的订阅附加项的响应正文条目，并使用该条目的 id 字段的值。	是的

请求主体

领域	类型	DESCRIPTION	必选
b2bKey	字符串	表示要更改其订阅的用户身份的 Microsoft Store ID 密钥。	是的
变更类型	字符串	以下字符串之一，可用于标识您希望进行的更改类型：取消：取消订阅。扩展：扩展订阅。如果指定此值，则还必须包含 extensionTimeInDays 参数。退款：将订阅退款给客户。 ToggleAutoRenew：停用订阅的自动续订功能。如果订阅当前禁用自动续订，则此值不起作用。	是的
延长时间（以天为单位）	字符串	如果 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"
    }
  ]
}

响应体

响应正文包含以下数据。

价值	类型	DESCRIPTION
自动续订	布尔型	指示是否已将订阅配置为在当前订阅期结束时自动续订。
受益人	字符串	与此订阅关联的权利受益者的 ID。
过期时间	字符串	订阅到期的日期和时间将以 ISO 8601 格式表示。仅当订阅处于特定状态时，此字段才可用。过期时间通常指示当前状态何时过期。例如，对于活动订阅，到期日期指示下次自动续订何时发生。
到期时间含宽限期	字符串	订阅将过期的日期和时间，包括宽限期，均采用 ISO 8601 格式。此值指示在订阅无法自动续订后，用户何时将失去对订阅的访问权限。
id	字符串	订阅的 ID。使用此值指示在调用更改用户方法订阅的计费状态时要修改的订阅。
isTrial	布尔型	指示订阅是否为试用版。
上次修改	字符串	上次修改订阅的日期和时间（采用 ISO 8601 格式）。
市场	字符串	用户获取订阅的国家/地区代码（采用双字母 ISO 3166-1 alpha-2 格式）。
productId	字符串	产品的应用商店 ID，表示 Microsoft Store 目录中的订阅附加组件。产品的应用商店 ID 示例为 9NBLGGH42CFD。
skuId 的	字符串	应用商店 ID 以及 SKU 代表 Microsoft Store 目录中的订阅加载项。 SKU 的示例商店 ID 为 0010。
开始时间	字符串	订阅的开始日期和时间，采用 ISO 8601 格式。
重复状态	字符串	以下值之一：无：这表示永久订阅。活动：订阅处于活动状态，用户有权使用服务。非活动：订阅已过期，用户关闭了订阅的自动续订选项。已取消：订阅被有意在到期日期之前终止，并可能含或不含退款。 InDunning：订阅处于催缴阶段（即订阅即将到期，微软尝试获取资金以自动续订订阅）。失败：催款期已过，订阅在多次尝试后未能成功续订。注意：无效/取消/失败是终端状态。当订阅进入其中一个状态时，用户必须重新购买订阅才能再次激活订阅。用户无权使用这些状态中的服务。当订阅取消时，到期时间将被更新为取消的日期和时间。订阅的 ID 在整个生命周期内保持不变。如果自动续订选项处于打开或关闭状态，则不会更改。如果用户在达到终端状态后重新购买订阅，则会创建新的订阅 ID。需要使用订阅的 ID 来执行对单个订阅的任何操作。当用户在取消或中止订阅后重新购买订阅时，若你查询该用户的结果，系统将显示两个条目：旧订阅 ID 为终端状态，而新订阅 ID 为活动状态。检查“recurrenceState”和“expirationTime”始终是一种好的做法，因为“recurrenceState”的更新可能会延迟几分钟（或偶尔数小时）。
取消日期	字符串	取消用户的订阅的日期和时间（采用 ISO 8601 格式）。