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

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

此终结点用于更改 Microsoft Store 中用户订阅产品的计费状态。你可以取消、延长、退款或禁用订阅的自动续订。 Microsoft.StoreServices 库 (GitHub) 通过 StoreServicesClient.RecurrenceChangeAsync API 提供此方法的功能。

先决条件

请查看服务到服务 API 的先决条件。此 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 中的 `id` 以及 Collections 查询 API 中的 `recurrenceData` 相同。	是

请求正文

参数	类型	说明	必需
`b2bKey`	`string`	表示你正在请求的用户身份的 User Purchase ID。请参阅用户 Store ID 密钥。	是
`changeType`	`string`	标识你要进行的更改类型。有关可能的值，请参阅更改类型操作表。	是
`extensionTimeInDays`	`string`	如果 changeType 参数的值为 Extend，则此参数指定要延长订阅的天数。对于测试场景，此数字可以为负数以从订阅中减去天数。	如果 changeType 值为 Extend，则是；否则否。
`sbx`	`string`	使用 UserStoreIds 进行身份验证时的可选值，用于指定结果应作用于的沙盒。若无此值，默认为 RETAIL 沙盒。X-Token 身份验证不需要此值，因为沙盒已在 X-Token 中指定。	否

更改类型操作

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

请求示例

以下示例演示如何使用此方法将订阅期延长五天。将 b2bKey 值替换为表示要更改订阅的用户身份的 User 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 响应正文。

此方法具有本文开头所述的相同 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 的更新可能延迟几分钟（偶尔几个小时）。

响应示例

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 从你的服务管理产品从你的服务管理退款和拒付使用 Microsoft Store API 验证你的服务使用 publisherQuery (Collections v9) 查询用户的产品和授权

Microsoft Store APIs

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

先决条件

请求

请求语法

请求标头

请求参数

请求正文

更改类型操作

请求示例

响应

响应正文

定期状态

响应示例

相关文章

​先决条件

​请求

​请求语法

​请求标头

​请求参数

​请求正文

​更改类型操作

​请求示例

​响应

​响应正文

​定期状态

​响应示例

​相关文章

先决条件

请求

请求语法

请求标头

请求参数

请求正文

更改类型操作

请求示例

响应

响应正文

定期状态

响应示例

相关文章