> ## 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.

# 从你的服务管理订阅产品

> 介绍如何使用 Recurrence 服务查询和管理你的订阅产品，以及处理用户的不同订阅状态。

对于订阅产品，请使用后端服务来验证状态并管理生命周期操作。使用 Recurrence API 可为你的支持团队和运营团队提供一种可靠的方式来检查、延长或取消订阅。

本文介绍如何在这些场景中使用 Recurrence 端点。

## 使用 Microsoft.StoreServices .NET 库和示例

若要帮助演示本文所述的原理和流程，请参阅 Microsoft.StoreServices 示例。该示例使用 Microsoft.StoreServices 库管理身份验证并调用 Microsoft Store 服务。示例服务本身包含用于管理订阅产品的示例逻辑，并提供配置指南以进行搭建。

* [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)
* [Microsoft.StoreServices 示例 (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)

## 订阅产品类型

Store 管理和附加内容订阅这两种产品类型都可以与 Recurrence 服务配合使用，以查看和管理用户的订阅。有关这些产品类型的更多信息，请参阅[选择合适的产品类型](/publishing/xstore-commerce/xstore-choosing-product-type#subscriptions)。

## 查询用户的订阅

将 [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query) 用作订阅状态的主要端点。它返回活动和历史订阅周期，以及变更操作所需的 `subscriptionId`。它还包含用于区分 Grace 和 Dunning 期的必要字段。

Collections API（[b2bLicensePreview (v8)](/reference/microsoft-store-apis/xstore-v8-query-for-products) 和 [publisherQuery (v9)](/reference/microsoft-store-apis/xstore-v9-query-for-products)）可以显示活跃订阅权益，但无法提供相同的定期详情。

## 客户端与服务到服务之间在满足权益检查上的延迟

当你发布向捆绑包中添加新项目（满足权益）的更新时，客户端与服务到服务 API 查询之间新项目的可见性会存在延迟。此延迟是由于不同商店系统以不同的时间间隔更新其目录缓存。当更改发布到目录时，本地授权服务通常先获得更新后的信息，而 publisherQuery 使用的缓存在两到三小时后更新。因此，请预期客户端 API 授予访问权限之后的几个小时内，你的服务到服务调用可能仍未反映新项目的所有权。

Recurrence 服务本身不受影响，仅 publisherQuery 或 b2bLicensePreview 端点针对新增项目的满足权益查询会受影响。

### 理解订阅的开始、续订和到期日期

订阅的 `StartTime` 日期是活跃订阅开始的日期。如果订阅设置为自动续订，开始日期保持不变，但到期日期会随着订阅在后续月份的续订而变化。如果订阅被取消、过期或撤销，当用户再次购买订阅时会创建一个新的订阅对象。新的活跃订阅周期的 `StartTime` 是他们激活或购买新订阅的当天。

Microsoft Store 中的订阅周期通常配置为按月数计。例如，1 个月、3 个月或 12 个月。当用户购买一个月订阅时，`StartTime` 是他们开始订阅当天的 UTC 午夜 (00:00:00)。`ExpirationTime` 是月数（不是天数）加到 `StartTime` 上再减去一秒 (23:59:59 UTC)。<br />这样订阅就在 UTC 午夜之前过期。

但是，某些月份的天数不同，会导致订阅从每月的 29 日、30 日或 31 日开始时出现冲突。<br />如果用户的 `StartTime` 落在这些日子的任何一天，`ExpirationTime` 会被修改为到期月最后一天的 23:59:59 UTC。这样，续订日期始终为下一个月第一天的 UTC 午夜 (00:00:00)，`ExpirationTime` 始终为月末的 23:59:59 UTC。

#### 一个月订阅的开始、续订和到期日期行为示例

| 购买日期                 | StartTime            | ExpireTime           | 自动续订日期               | 活跃天数   |
| -------------------- | -------------------- | -------------------- | -------------------- | ------ |
| 2023-02-27T12:00:00Z | 2023-02-27T00:00:00Z | 2023-03-26T23:59:59Z | 2023-03-27T00:00:00Z | 28     |
| 2023-03-27T12:00:00Z | 2023-03-27T00:00:00Z | 2023-04-26T23:59:59Z | 2023-05-27T00:00:00Z | 31     |
| 2023-03-29T12:00:00Z | 2023-03-29T00:00:00Z | 2023-04-30T23:59:59Z | 2023-05-01T00:00:00Z | 32     |
| 2023-04-29T12:00:00Z | 2023-04-29T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 33     |
| 2023-04-30T12:00:00Z | 2023-04-30T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z | 32     |
| 2024-02-27T12:00:00Z | 2024-02-27T00:00:00Z | 2024-03-26T23:59:59Z | 2024-03-27T00:00:00Z | 29（闰年） |

### 理解 Grace 和 Dunning 状态

如果在 `ExpirationTime` 时自动续订付款失败，订阅会进入 Grace，如果仍未解决则进入 Dunning。两个时期都报告状态为 `InDunning`，因此通过将当前 UTC 时间与 `ExpirationTimeWithGrace` 比较来确定当前处于哪个时期。

当用户订阅处于 Grace 或 Dunning 期间时，你应提醒用户在 [Microsoft 账户服务和订阅](https://account.microsoft.com/services)中检查其计费状态。

要将账号正确设置为每种状态进行测试，请参阅[测试订阅产品](#testing-subscription-products)。

#### Grace 期

在 Grace 期间，保持订阅福利处于启用状态，而 Store 会重试续订付款。如果续订成功，已使用的 Grace 天数会从下一个周期中扣除。如果在 `ExpirationTimeWithGrace` 之前付款未解决，订阅将进入 Dunning。

#### Dunning 期

Dunning 在 Grace 结束后开始。在此期间禁用订阅福利。用户在 Dunning 期间无法重新购买或兑换相同的订阅。如果整个 Dunning 期间付款仍未解决，订阅将变为非活跃。

### Grace 和 Dunning 时长

| 订阅类型        | 订阅时长 | Grace | Dunning（Grace 之后） |
| ----------- | ---- | ----- | ----------------- |
| 附加内容订阅      | 任意   | 3 天   | 39 天              |
| Store 管理的订阅 | 任意   | 7 天   | 36 天              |

## 更改用户的订阅

你的服务也可以通过 [purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/reference/microsoft-store-apis/xstore-v8-recurrence-change) 修改订阅。支持的操作包括添加天数、禁用自动续订以及取消订阅。你的服务需要 `recurrenceId`（与 [RecurrenceQuery API](/reference/microsoft-store-apis/xstore-v8-recurrence-query) 中的 `id` 以及 [Collections 查询 API](/reference/microsoft-store-apis/xstore-v9-query-for-products) 中的 `recurrenceData` 值相同）才能操作用户的订阅。

以下是 Recurrence Change 端点如何与你的服务配合使用的一些示例：

* 为遭遇服务停机的用户订阅添加时间。
* 与你的客户支持团队集成，帮助用户了解其订阅状态、取消操作等。
* 允许用户更改自动续订或结束订阅等设置的游戏内 UI。

## 测试订阅产品

[Recurrence Change API](/reference/microsoft-store-apis/xstore-v8-recurrence-change) 也可用于测试。`Extend` 接受负数天数值，可让你将测试订阅推进到目标状态。

### 测试 Active、Inactive 和 Canceled 状态

在测试订阅的 Active、Inactive 和 Canceled 状态时，可以在订阅上使用 \$0.00 的基础价格。将订阅添加到测试账号以验证 Active 状态，并使用 Recurrence Change 端点禁用自动续订。然后使用 Recurrence Change 端点取消订阅，或减去足够的天数使 `ExpirationTime` 早于当前 UTC 日期时间。

### 测试 Grace 和 Dunning 状态

要测试 Grace 和 Dunning 状态，订阅必须具有非零价格。<br />此外，测试账号必须配置为当 `ExpirationTime` 到达时后续付款不会成功。目前 Microsoft Store 没有测试支付工具，因此设置账号最简单的方法是使用预付卡货币代码：

1. 在你的测试环境中将订阅设置为较低的价格点，例如 \$0.99。
2. [购买 XBOX 预付礼品卡](https://www.microsoft.com/en-us/p/xbox-gift-card-digital-code/cfq7ttc0k63h/0002?activetab=pivot:overviewtab)，金额为 $1.00 或 $2.00，覆盖第一次订阅购买（加税），但不足以续订。
3. 在你的测试账号上兑换礼品卡。
4. 在测试账号上购买订阅。
5. 确保为订阅启用了自动续订，但没有足够的资金续订。
6. 使用 Recurrence Change 将订阅的 `ExpirationTime` 移到接下来的 24 小时内（见下方注释）。
7. 等待 `ExpirationTime` 自然过去，并等待状态显示为 `InDunning`（在 `ExpirationTime` 之后最多可能需要 24 小时）。

若要获得准确的 Grace -> Dunning -> Inactive 行为，请在设置测试后让账号自然推进。

<Note>
  要将账号正确带入 Grace 和 Dunning 期的 “InDunning” 状态，账号必须自然通过 `ExpirationTime` 和 `ExpirationTimeWithGrace` 日期。减少天数时，将 `ExpirationTime` 目标设定在接下来的 24 小时内，然后让时间自然流逝。如果将 `ExpirationTime` 移到已经过去的时间点，`InDunning` 可能不会出现，测试状态可能变得无效。解决此问题的唯一方法是取消该订阅并创建新的测试订阅。
</Note>

## 另请参阅

[商务概述](/publishing/xstore-commerce/xstore-commerce-overview)

[Microsoft Store 服务 API](/reference/microsoft-store-apis/index)

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query)

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/reference/microsoft-store-apis/xstore-v8-recurrence-change)

[Microsoft.StoreServices 库 (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)

[Microsoft.StoreServices 示例 (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)


## Related topics

- [从你的服务管理消耗品产品](/zh-CN/publishing/xstore-commerce/xstore-managing-consumables.md)
- [从你的服务查询用户权益](/zh-CN/publishing/xstore-commerce/xstore-query-entitlements.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [collections.mp.microsoft.com/v8.0/collections/consume](/zh-CN/reference/microsoft-store-apis/xstore-v8-consume.md)
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/zh-CN/reference/microsoft-store-apis/xstore-v9-query-for-products.md)