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

  • Article

Note

If using a development sandbox, currently this API will only work if the subscription product is published to the RETAIL sandbox. If the subscription is not published to RETAIL you will get back an HTTP 400 error response with a message stating "Requested catalog product data was not found". This is a known issue that has a work-item to be resolved in a future release. Until then, you will need to publish the subscription to either a private flight group or as hidden in RETAIL to be able to use this API.

This endpoint is used to change the billing state of the user's subscription product in the Microsoft Store. You can cancel, extend, refund, or disable automatic renewal for a subscription.

The Microsoft.StoreServices library (GitHub) provides the functionality of this method through the StoreServicesClient.RecurrenceChangeAsync API.

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/{recurrenceId}/change

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 parameters

Header Type Description Required
recurrenceId string Unique to the user's subscription and is obtained from the results of a query to purchase.mp.microsoft.com/v8.0/b2b/recurrences/query. Yes

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
changeType string Identifies the type of change you want to make. See table below for the possible Change Type values. Yes
extensionTimeInDays string If the changeType parameter has the value Extend, this parameter specifies the number of days to extend the subscription. For testing scenarios, this number can be negative to remove days from the subscription. Yes, if changeType has the value Extend; otherwise, no.
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

Change Type operations

Change Type Description
Cancel Cancels the subscription.
Extend Extends the subscription. If you specify this value, you must also include the extensionTimeInDays parameter in the request body.
Refund Refunds the subscription to the customer.
ToggleAutoRenew Disables automatic renewal for the subscription. If automatic renewal is currently disabled for the subscription, this value does nothing.

Request example

The following example demonstrates how to use this method to extend the subscription period by 5 days. Replace the b2bKey value with the User Store ID key that represents the identity of the user whose subscription you want to change.

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"
}

Response

This method returns a JSON response body that contains information about the subscription add-on that was modified, including any fields that were modified. The following example demonstrates a response body for this method.

Note

If using a development sandbox, currently this API will only work if the subscription product is published to the RETAIL sandbox. If the subscription is not published to RETAIL you will get back an HTTP 400 error response with a message stating "Requested catalog product data was not found". This is a known issue that has a work-item to be resolved in a future release. Until then, you will need to publish the subscription to either a private flight group or as hidden in RETAIL to be able to use this API.

Response body

Parameter Type Description Required
continuationToken string If there are multiple sets of products, this token is returned when the page limit is reached. You can specify this continuation token in subsequent calls to retrieve 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 The Subscription is valid, and the 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
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

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