purchase.mp.microsoft.com/v8.0/b2b/recurrences/query

此终结点用于查询用户通过 Microsoft Store 拥有的订阅产品类型的状态。 它提供的信息比这些订阅的 Collections 服务更多，包括自动续订费用失败时的产品的宽限期。

先决条件

要使用此 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/query

请求头文件

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

请求正文

参数	类型	描述	必需
b2bKey	string	代表你要查询其订单的用户标识的用户购买 ID。 请参阅用户 Store ID 键。	是
sbx	string	使用 UserStoreIds 进行身份验证的可选值，该值指定应将结果限定到的沙盒。 不带此值的默认值为 RETAIL 沙盒。 X 令牌身份验证不需要此值，因为沙盒是在 X 令牌中指定的。	否
continuationToken	string	如果有多组产品不能适用于 maxPageSize，则响应正文将在达到页面限制时返回延续令牌。 在后续调用中提供延续令牌以检索来自先前请求查询的剩余产品。	否

请求示例

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "b2bKey":"[UserPurchaseID]",
  "sbx": "XDKS.1"
}

响应

响应正文

参数	类型	描述	必需
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
date: Tue, 17 Aug 2021 21:22:28 GMT
content-type: application/json; charset=utf-8
content-length: 2382
ms-cv: aft4s000mwNmYF.0
x-content-type-options: nosniff
x-envoy-upstream-service-time: 2099

{
    "items": [
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-08-25T23:59:59.00+00:00",
            "expirationTimeWithGrace": "2021-09-08T23:59:59.00+00:00",
            "id": "mdr:0:1ecc1424ed8f457ab6107f08033e6b50:907f0a31-035c-41a2-b70b-5a62925a4f92",
            "isTrial": false,
            "lastModified": "2021-07-26T22:59:55.99+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Active"
        },
        {
            "autoRenew": true,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T21:08:30.52+00:00",
            "expirationTimeWithGrace": "2021-07-26T21:08:30.52+00:00",
            "id": "mdr:0:50c7396d0e5f4e7f9deeede3ba25f1a4:87c4cfae-ed1d-400f-a6b0-19fdb3c327f5",
            "isTrial": false,
            "lastModified": "2021-07-26T21:08:34.61+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-15T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T21:08:31.52+00:00"
        },
        {
            "autoRenew": false,
            "beneficiary": "pub:NoUserIdProvided",
            "expirationTime": "2021-07-26T22:35:29.54+00:00",
            "expirationTimeWithGrace": "2021-07-26T22:35:29.54+00:00",
            "id": "mdr:0:528115d9771f4e49b79550790fd4a263:f30a646e-54cf-4fe8-8c95-7add9fc2ebde",
            "isTrial": false,
            "lastModified": "2021-07-26T22:35:33.96+00:00",
            "market": "US",
            "productId": "CFQ7TTC0HC8Z",
            "skuId": "0002",
            "startTime": "2021-07-26T00:00:00.00+00:00",
            "recurrenceState": "Canceled",
            "cancellationDate": "2021-07-26T22:35:30.54+00:00"
        },
    ]
}

示例响应说明

在上面的示例中，此用户有两个以前取消的订阅期和一个当前处于活动状态的订阅期，从 2021 年 7 月 26 日开始。 订阅期的结束日期为 2021 年 8 月 26 日。 由于用户已注册自动续订，Microsoft Store 将尝试续订订阅，并在 2021 年 8 月 26 日前后处理付款。 如果用户的帐户无法完成订阅续订，则订阅的状态将更改为“InDunning”，但在宽限期结束之前，用户仍应获得订阅权益。 当宽限期结束时（2021 年 9 月 8 日），如果应用商店无法完成续订购买，则即使状态仍为“InDunning”，服务也不应再向用户授予订阅权益。 在宽限期之后，用户将被阻止重新购买或重新注册订阅，并且必须修复其付款方式才能再次获取活动订阅。 这是因为他们现已在宽限期内获得了 2 周的权益，而他们现在处于需要支付的欠款状态。 当他们解析其帐户的付款方式时，将从其下一个订阅期中删除 2 周，以涵盖他们之前使用的宽限期。

使用延续令牌请求剩余结果

如果查询的结果多于单个响应中可以返回的结果，则初始查询响应将具有 continuationToken。 然后，可以通过将延续令牌添加到上一个请求正文的副本，在后续请求中使用此 continuationToken。

延续请求示例：

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Host: purchase.mp.microsoft.com
Authorization: Bearer [Microsoft Entra ID bearer token]
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
  "continuationToken":"[Continuation Token]",
  "b2bKey":"[UserPurchaseID]",
  "sbx": "XDKS.1"
}

相关主题

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

管理来自服务的产品

管理服务的退款和退单拒付

使用 Microsoft Store API 验证您的服务

使用 PublisherQuery（集锦 v9）查询用户的产品和权利。