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

此终结点用于查询 Microsoft Store 中用户的订阅产品状态。它比 Collections 提供更多详细信息，包括自动续订失败后的宽限期数据。

先决条件

请查看服务到服务 API 的先决条件。此 API 仅支持 Microsoft Entra ID 身份验证类型。如果产品配置未在 Partner Center 发布，可能会成功但不返回任何结果。

请求

请求语法

方法	请求 URI
`POST`	`purchase.mp.microsoft.com/v8.0/b2b/recurrences/query`

请求标头

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

请求正文

参数	类型	说明	必需
`b2bKey`	`string`	表示你正在请求的用户身份的 User Purchase ID。请参阅用户 Store ID 密钥。	是
`sbx`	`string`	使用 UserStoreIds 进行身份验证时的可选值，用于指定结果应作用于的沙盒。若无此值，默认为 RETAIL 沙盒。X-Token 身份验证不需要此值，因为沙盒已在 X-Token 中指定。	否
`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`	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
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"
        },
    ]
}

响应示例说明

此响应显示了用户的三个订阅条目：两个处于 Canceled 状态，一个当前 Active 状态并在 2021 年 7 月 26 日开始。活动订阅的期限于 2021 年 8 月 26 日结束，并设置为在该日期自动续订。如果续订付款失败，订阅将转到宽限窗口，用户仍会在 expirationTimeWithGrace（此示例中为 2021 年 9 月 8 日）之前收到权益。当订阅进入宽限窗口时，recurrenceState 变为 InDunning。宽限期结束后，订阅进入催缴窗口。在此期间，你的服务停止授予权益，用户必须修复其付款方式。用户在此期间无法取消或开始新订阅。处理付款后，宽限时间（此示例中为两周）会从下一个付费期中扣除。

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

如果你的查询包含比单个响应可返回更多的结果，则初始查询响应中会包含 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//change 从你的服务管理产品从你的服务管理退款和拒付使用 Microsoft Store API 验证你的服务使用 publisherQuery (Collections v9) 查询用户的产品和授权

Microsoft Store APIs

先决条件

请求

请求语法

请求标头

请求正文

请求示例

响应

响应正文

定期状态

响应示例

响应示例说明

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

相关文章

​先决条件

​请求

​请求语法

​请求标头

​请求正文

​请求示例

​响应

​响应正文

​定期状态

​响应示例

​响应示例说明

​使用延续令牌请求其余结果

​相关文章

先决条件

请求

请求语法

请求标头

请求正文

请求示例

响应

响应正文

定期状态

响应示例

响应示例说明

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

相关文章