> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change

> Microsoft Store v8 recurrences change 终结点，允许游戏服务按续订 ID 取消、延长或退款用户的订阅续订。

> [!NOTE]
>
> 仅当订阅发布到 RETAIL 时，此 API 才有效。如果使用开发沙盒，请先将订阅发布到私有飞行组或以隐藏方式发布到 RETAIL，然后再调用此 API。如果订阅未发布到 RETAIL，则响应为 HTTP 400 错误，并显示消息“找不到请求的目录产品数据”。

此终结点用于更改 Microsoft Store 中用户订阅产品的计费状态。
你可以取消、延长、退款或禁用订阅的自动续订。

[Microsoft.StoreServices 库 (GitHub)](https://github.com/microsoft/Microsoft-Store-Services) 通过 StoreServicesClient.RecurrenceChangeAsync API 提供此方法的功能。

## 先决条件

请查看[服务到服务 API 的先决条件](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-authenticating-service.md)。

此 API 仅支持 Microsoft Entra ID 身份验证类型。

如果产品配置未在 Partner Center 发布，可能会成功但不返回任何结果。

## 请求

### 请求语法

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

### 请求标头

| 标头 | 类型 | 说明 |
| - | - | - |
| `Authorization` | `string` | 必需。形式为 `Bearer` \<*token*> 的 Microsoft Entra ID 服务访问令牌。 |
| `Host` | `string` | 必须设置为值 `purchase.mp.microsoft.com`。 |
| `Content-Length` | `number` | 请求正文的长度。 |
| `Content-Type` | `string` | 指定请求和响应类型。目前唯一支持的值是 `application/json`。 |

### 请求参数

| 标头 | 类型 | 说明 | 必需 |
| - | - | - | - |
| `recurrenceId` | `string` | 用户订阅的唯一值，与 [RecurrenceQuery API](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-recurrence-query.md) 中的 `id` 以及 [Collections 查询 API](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v9-query-for-products.md) 中的 `recurrenceData` 相同。 | 是 |

### 请求正文

| 参数 | 类型 | 说明 | 必需 |
| - | - | - | - |
| `b2bKey` | `string` | 表示你正在请求的用户身份的 User Purchase ID。请参阅[用户 Store ID 密钥](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-requesting-userstoreid.md#step-4-create-a-user-store-id-key)。 | 是 |
| `changeType` | `string` | 标识你要进行的更改类型。有关可能的值，请参阅[更改类型操作](#change-type-operations)表。 | 是 |
| `extensionTimeInDays` | `string` | 如果 changeType 参数的值为 Extend，则此参数指定要延长订阅的天数。对于测试场景，此数字可以为负数以从订阅中减去天数。 | 如果 changeType 值为 *Extend*，则是；否则否。 |
| `sbx` | `string` | 使用 UserStoreIds 进行身份验证时的可选值，用于指定结果应作用于的沙盒。若无此值，默认为 RETAIL 沙盒。X-Token 身份验证不需要此值，因为沙盒已在 X-Token 中指定。 | 否 |

### 更改类型操作

| 更改类型 | 说明 |
| - | - |
| `Cancel` | 取消订阅。 |
| `Extend` | 延长订阅。如果指定此值，还必须在请求正文中包含 `extensionTimeInDays` 参数。 |
| `Refund` | 向客户退还订阅款项。 |
| `ToggleAutoRenew` | 禁用订阅的自动续订。如果订阅当前已禁用自动续订，此值不执行任何操作。 |

### 请求示例

以下示例演示如何使用此方法将订阅期延长五天。将 b2bKey 值替换为表示要更改订阅的用户身份的 User Store ID 密钥。

```html theme={null}
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 响应正文。

> [!NOTE]
>
> 此方法具有本文开头所述的相同 RETAIL 发布要求。

### 响应正文

| 参数 | 类型 | 说明 | 必需 |
| - | - | - | - |
| `continuationToken` | `string` | 如果有多组产品，则在达到页面限制时返回此令牌。你可以在后续调用中指定此延续令牌以检索其余产品。 | 否 |
| `items` | `list<RecurrenceItem>` | 指定用户的产品数组。有关详细信息，请参阅下表。 | 是 |

`RecurrenceItem` 对象包含以下参数。

| 参数 | 类型 | 说明 | 必需 |
| - | - | - | - |
| `autoRenew` | `bool` | 指示用户是否已注册在下一个计费周期结束时自动续订其订阅。 | 是 |
| `beneficiary` | `string` | User Purchase ID 中受益人的发布者 ID。 | 是 |
| `expirationTime` | `DateTime` | 订阅到期的 UTC 日期和时间。 | 是 |
| `expirationTimeWithGrace` | `DateTime` | 如果在 ExpirationTime 时自动续订失败，用户宽限期结束的 UTC 日期和时间。在宽限期内，用户仍应有权访问并被视为有效订阅者，但会收到通知需要修复其自动续订付款。 | 是 |
| `id` | `string` | 用于将此集合项与用户拥有的其他项区分开的 ID。此 ID 对每个产品是唯一的。 | 是 |
| `isTrial` | `bool` | 指示产品是否处于试用期，例如订阅。 | 是 |
| `lastModified` | `DateTime` | 此项目上次修改的 UTC 日期。 | 是 |
| `market` | `string` | 购买产品所在的国家/地区，遵循两个字符的 ISO 3166 国家/地区代码。例如：US。 | 是 |
| `productId` | `string` | 也称为 Microsoft Store 目录中产品的 Store ID。产品的 Store ID 示例为 9NBLGGH42CFD。 | 是 |
| `recurrenceState` | `string` | 定期的当前状态。请参阅“定期状态”。 | 是 |
| `skuId` | `string` | 如果 Microsoft Store 目录中该产品有多个产品/服务的话，特定 SKU 的标识符。SKU 的 Store ID 示例为 0010。 | 是 |
| `startTime` | `DateTime` | 订阅开始的 UTC 日期。 | 是 |
| `cancellationDate` | `DateTime` | 订阅被取消的 UTC 日期。 | 否 |

### 定期状态

| 值 | 说明 |
| - | - |
| `None` | 表示永久订阅。 |
| `Active` | 订阅有效，用户有权享受订阅权益。 |
| `Inactive` | 订阅已过到期日期，用户已关闭订阅的自动续订选项。 |
| `Canceled` | 订阅在到期日期之前有意终止，无论是否退款。 |
| `InDunning` | 订阅处于催缴状态（即订阅接近到期，Microsoft 正在尝试获取资金以自动续订订阅）。如果当前日期在 expirationTimeWithGrace 值之前，则用户仍应有权享受订阅权益。如果当前日期在 expirationTimeWithGrace 值之后，则用户不应有权访问订阅权益。 |
| `Failed` | 催缴期结束，订阅在多次尝试后未能续订。 |

* *Inactive/Canceled/Failed* 是终止状态。当订阅进入这些状态之一时，用户必须重新购买订阅才能再次激活。用户在这些状态下无权使用服务。
* 当订阅取消时，`expirationTime` 会更新为取消的日期和时间。
* 订阅的 ID 在其整个生命周期中保持不变。它不会因为自动续订选项打开或关闭而变化。如果用户在达到终止状态后重新购买订阅，将创建新的订阅 ID。
* 应使用订阅的 ID 对单个订阅执行任何操作。
* 当用户在取消或停止后重新购买订阅时，如果你查询该用户的结果，将获得两个条目：一个具有旧订阅 ID 处于终止状态，另一个具有新订阅 ID 处于活动状态。
* 始终最好同时检查 recurrenceState 和 `expirationTime`，因为 `recurrenceState` 的更新可能延迟几分钟（偶尔几个小时）。

### 响应示例

```json theme={null}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 431
ms-correlationid: 95b2aee4-1118-437b-8910-a2f7d84d0766
ms-cv: Kl684e1htkqb19Ch.0
Date: Thu, 03 Mar 2022 23:19:12 GMT

{
    "autoRenew": true,
    "beneficiary": "pub:NoUserIdProvided",
    "expirationTime": "2022-03-03T23:59:59.00+00:00",
    "expirationTimeWithGrace": "2022-03-17T23:59:59.00+00:00",
    "id": "mdr:0:3172048a2d1849ba9a24fd305854d4a8:cedca1d3-9580-4229-9cb5-f00c4547078c",
    "isTrial": false,
    "lastModified": "2022-03-03T23:19:12.26+00:00",
    "market": "US",
    "productId": "CFQ7TTC0HC8Z",
    "skuId": "0003",
    "startTime": "2022-03-03T00:00:00.00+00:00",
    "recurrenceState": "Active"
}

```

## 相关文章

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)

[从你的服务管理产品](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-authenticating-service.md)

[从你的服务管理退款和拒付](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-managing-refunds.md)

[使用 Microsoft Store API 验证你的服务](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-authenticating-service.md)

[使用 publisherQuery (Collections v9) 查询用户的产品和授权](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v9-query-for-products.md)


## Related topics

- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)
- [从你的服务管理订阅产品](https://devdocs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-managing-subscriptions.md)
- [Microsoft Store 服务 API（内容）](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-nav.md)
- [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](https://devdocs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)