purchase.mp.microsoft.com/v8.0/b2b/recurrences/query
This endpoint is used to query for the status of the subscription product types that the user owns through the Microsoft Store. It provides more information than the Collections service for these subscriptions including the product's grace period when an auto-renew charge has failed.
Prerequisites
To use this API, you need the following:
- A Microsoft Entra ID access token that has the audience URI value
https://onestore.microsoft.com
- A User Purchase ID key that represents the identity of the user for whom you want to grant a free product
For more information, see Requesting a User Store ID for service-to-service authentication.
Additionally, the products that you want to be visible to your service require additional configuration in Partner Center.
See Additional configuration required to view and manage products with a User Store ID / Microsoft Entra ID auth for how to properly configure your products.
Note
If the product configuration has not been done and published through Partner Center, the calls to Purchase services will succeed but there will not be any results in the response.
Request
Request syntax
Method | Request URI |
---|---|
POST |
purchase.mp.microsoft.com/v8.0/b2b/recurrences/query |
Request header
Header | Type | Description |
---|---|---|
Authorization |
string |
Required. The Microsoft Entra ID service access token in the form Bearer <token>. |
Host |
string |
Must be set to the value purchase.mp.microsoft.com . |
Content-Length |
number |
The length of the request body. |
Content-Type |
string |
Specifies the request and response type. Currently, the only supported value is application/json . |
Request body
Parameter | Type | Description | Required |
---|---|---|---|
b2bKey |
string |
The User Purchase Id that represents the identity of the user for whom you are requesting. See User Store ID key. | Yes |
sbx |
string |
Optional value for authenticating with UserStoreIds that specifies the Sandbox the results should be scoped to. Default without this value is the RETAIL sandbox. X-Token auth does not need this value as the Sandbox is specified within the X-Token. | No |
continuationToken |
string |
If there are multiple sets of products that can't fit within maxPageSize , the response body returns a continuation token when the page limit is reached. Provide that continuation token in the subsequent call to retrieve the remaining products from the previous request's query. |
No |
Request example
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"
}
Response
Response body
Parameter | Type | Description | Required |
---|---|---|---|
continuationToken |
string |
This token is returned when the page limit is reached. You can specify this continuation token in a subsequent calls to retrieve the remaining products. | No |
items |
list<RecurrenceItem> |
An array of products for the specified user. For more information, see the following table. | Yes |
The RecurrenceItem
object contains the following parameters.
Parameter | Type | Description | Required |
---|---|---|---|
autoRenew |
bool |
Indicates if the user is enrolled to have their subscription auto-renew at the end of the next billing cycle. | Yes |
beneficiary |
string |
The Publisher Id of the beneficiary within the User Purchase Id. | Yes |
expirationTime |
DateTime |
The UTC date and time that the subscription will or has expired | Yes |
expirationTimeWithGrace |
DateTime |
The UTC date and time that the user's Grace period will end if auto-renew fails at the ExpirationTime. During Grace, users should still have access and be considered valid subscribers, but notified they need to fix their auto-renew payment. | Yes |
id |
string |
An ID that identifies this collection item from other items that the user owns. This ID is unique per product. | Yes |
isTrial |
bool |
Indicates if the product is in a trial period, such as a subscription. | Yes |
lastModified |
DateTime |
The UTC date that this item was last modified. | Yes |
market |
string |
The country/region the product was purchased in following the two-character ISO 3166 country/region code. EX: US. | Yes |
productId |
string |
Also referred to as the Store ID for the product within the Microsoft Store catalog. An example Store ID for a product is 9NBLGGH42CFD. | Yes |
recurrenceState |
string |
Current state of the recurrence. See Recurrence Sates. | Yes |
skuId |
string |
The specific SKU identifier if there are multiple offerings of the product in the Microsoft Store catalog. An example Store ID for a SKU is 0010. | Yes |
startTime |
DateTime |
The UTC date that the subscription became or will become valid. | Yes |
cancellationDate |
DateTime |
The UTC date that the subscription was canceled. | No |
Recurrence Sates
Value | Description |
---|---|
None |
This indicates a perpetual subscription. |
Active |
Subscription is valid and user is entitled to the subscription benefits. |
Inactive |
The subscription is past the expiration date, and the user turned off the automatic renew option for the subscription. |
Canceled |
The subscription has been purposefully terminated before the expiration date, with or without a refund. |
InDunning |
The subscription is in dunning (that is, the subscription is nearing expiration, and Microsoft is trying to acquire funds to automatically renew the subscription). If the current date is before the expirationTimeWithGrace value, user should still be entitled to the subscription benefits. If current date is after the expirationTimeWithGrace value, user should not have access to subscription benefits. |
Failed |
The dunning period is over, and the subscription failed to renew after several attempts. |
- Inactive/Canceled/Failed are terminal states. When a subscription enters one of these states, the user must repurchase the subscription to activate it again. The user is not entitled to use the services in these states.
- When a subscription is Canceled, the expirationTime will be updated with the date and time of the cancellation.
- The ID of the subscription will remain the same during its entire lifetime. It will not change if the auto-renew option is turned on or off. If a user repurchases a subscription after reaching a terminal state, a new subscription ID will be created.
- The ID of a subscription should be used to execute any operation on an individual subscription.
- When a user repurchases a subscription after canceling or discontinuing it, if you query the results for the user you will get two entries: one with the old subscription ID in a terminal state, and one with the new subscription ID in an active state.
- It's always a good practice to check both recurrenceState and expirationTime, since updates to recurrenceState can potentially be delayed by a few minutes (or occasionally hours).
Response Example
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"
},
]
}
Explanation of example response
From the above example, this user has two previously canceled subscription periods and a currently active one that started on July 26, 2021. The end-date of the subscription period is Aug 26, 2021. Because the user is enrolled in auto-renew the Microsoft Store will attempt to renew the subscription with a payment processed around Aug 26, 2021. If the user's account is unable to complete the subscription renewal, the status of the subscription will change to 'InDunning' but the user should still receive access to subscription benefits until the end of the grace period. At the end of the grace period (Sept 08, 2021) if the store was unable to complete the renewal purchase, the service should no longer grant subscription benefits to the user even if the status is still 'InDunning'. After the Grace period, the user is blocked from re-purchasing or re-enrolling in the subscription and must fix their payment instrument to get an active subscription once again. This is because they have now received 2 weeks of benefits during the Grace period that they are now in a deficit to pay for. When they resolve their account's payment instrument, 2 weeks will be removed from their next subscription period to cover the grace period that they used previously.
Requesting remaining results with the continuation token
If your query has more results than can be returned in a single response, your initial query response will have a continuationToken. You can then use this continuationToken in a follow up request by adding the continuation token to a copy of the previous request body.
Example continuation request:
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"
}
Related topics
purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change
Manage products from your services
Managing refunds and chargebacks from your service
Authenticating your service with the Microsoft Store APIs
Using PublisherQuery (Collections v9) to query a user's products and entitlements