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

项目
06/20/2024

注意

如果使用开发沙盒，则目前仅当订阅产品发布到 RETAIL 沙盒时，此 API 才有效。如果订阅未发布到 RETAIL，将返回 HTTP 400 错误响应，并显示一条消息“找不到请求的目录产品数据”。这是一个已知问题，需要在将来的版本中解决工作项。在此之前，需要将订阅发布到专用外部测试版组或在 RETAIL 中以隐藏的形式发布订阅，以便能够使用此 API。

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

Microsoft.StoreServices 库 (GitHub) 通过 StoreServicesClient.RecurrenceChangeAsync API 提供此方法的功能。

先决条件

要使用此 API，需具备以下各项：

具有受众 URI 值 https://onestore.microsoft.com 的 Microsoft Entra ID 访问令牌
一个代表要向其授予免费产品的用户身份的用户购买 ID 密钥

有关详细信息，请参阅请求一个用户 Store ID 用于服务间身份验证。

此外，要对服务可见的产品需要在合作伙伴中心中进行其他配置。

有关如何正确配置产品，请参阅使用用户 Store ID/Microsoft Entra ID 身份验证查看和管理产品所需的其他配置。

注意

如果尚未完成产品配置并通过合作伙伴中心发布，则对购买服务的调用将成功，但响应中不会有任何结果。

请求

请求语法

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

请求头文件

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

请求参数

标头	类型	说明	必需
`recurrenceId`	`string`	对于用户订阅是唯一的，可从对 purchase.mp.microsoft.com/v8.0/b2b/recurrences/query 的查询结果中获得。	是

请求正文

参数	类型	说明	必需
`b2bKey`	`string`	代表你要查询其订单的用户标识的用户购买 ID。请参阅用户 Store ID 键。	是
`changeType`	`string`	标识要进行的更改的类型。有关可能的更改类型值，请参阅下表。	是
`extensionTimeInDays`	`string`	如果 changeType 参数的值为 Extend，则此参数用于指定订阅的延长天数。对于测试方案，此数字可以为负数，表示将从订阅中删除天数。	如果 changeType 的值为 Extend，则为是；否则，为否。
`sbx`	`string`	使用 UserStoreIds 进行身份验证的可选值，该值指定应将结果限定到的沙盒。不带此值的默认值为 RETAIL 沙盒。 X 令牌身份验证不需要此值，因为沙盒是在 X 令牌中指定的。	否

更改类型操作

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

请求示例

以下示例展示了如何使用此方法将订阅期延长 5 天。将 b2bKey 值替换为用户 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 响应正文。下面的示例展示了此方法的响应正文。

注意

响应正文

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

RecurrenceItem 对象包含以下参数。

参数	类型	说明	必需
`autoRenew`	`bool`	指示用户是否已注册，以便在下一个计费周期结束时自动续订其订阅。	是
`beneficiary`	`string`	用户购买 ID 内的受益人的发布者 ID。	是
`expirationTime`	`DateTime`	订阅将或已过期的 UTC 日期和时间	是
`expirationTimeWithGrace`	`DateTime`	当自动续订在 ExpirationTime 失败时，用户宽限期将结束的 UTC 日期和时间。在 Grace 期间，用户仍应具有访问权限，并被视为有效的订阅者，但通知他们需要修复其自动续订付款。	是
`id`	`string`	用于从用户所拥有的其他项目标识此收藏项目的 ID。此 ID 对于每个产品都是唯一的。	是
`isTrial`	`bool`	指示产品是否处于试用期（如订阅期）。	是
`lastModified`	`DateTime`	最后修改此项目的 UTC 日期。	是
`market`	`string`	按照两个字符的 ISO 3166 国家/地区代码购买产品的国家/地区。 EX：美国。	是
`productId`	`string`	在 Microsoft Store 目录中也称为产品的 Store ID。产品的示例 Microsoft Store ID 为 9NBLGGH42CFD。	是
`recurrenceState`	`string`	重复周期的当前状态。请参阅 Recurrence Sates。	是
`skuId`	`string`	如果 Microsoft Store 目录中有多种产品/服务，则为特定的 SKU 标识符。 SKU 的示例 Microsoft Store ID 为 0010。	是
`startTime`	`DateTime`	订阅生效或将生效的 UTC 日期。	是
`cancellationDate`	`DateTime`	取消订阅的 UTC 日期。	否

Recurrence Sates

值	说明
`None`	这表示永久订阅。
`Active`	订阅有效，用户有资格享受订阅权益。
`Inactive`	订阅已过期，并且用户已关闭订阅的自动续订选项。
`Canceled`	订阅已在截止日期之前被故意终止，提供或不提供退款。
`InDunning`	订阅正处于催缴状态（即，订阅即将过期，且 Microsoft 正尝试获取款项以自动续订此订阅）。如果当前日期早于 expirationTimeWithGrace 值，则表示用户仍应有资格享受订阅权益。如果当前日期晚于 expirationTimeWithGrace 值，则表示用户无权享受订阅权益。
`Failed`	催缴期已结束，并且在多次尝试后仍无法续订此订阅。

非活动/已取消/失败为终端状态。当订阅处于这些状态之一时，用户必须重新购买订阅才能再次激活订阅。在这些状态下，用户无权使用服务。
当订阅处于“已取消”状态时，expirationTime 将会更新为取消的日期和时间。
在整个生命周期中，订阅 ID 将保持相同。打开或关闭自动续订选项并不会更改订阅 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（集锦 v9）查询用户的产品和权利。