Managing subscription products from your service

Article
03/28/2024

If your title or publisher uses a subscription product, it is a best practice to develop a back-end service to validate the user's subscription status and manage the subscription. This allows your services additional insight into the user's subscription status and your support teams to help resolve issues with, add time to, or cancel the user's subscription.

This article will outline how to use the Recurrence service endpoints to enable these scenarios on your own service.

Utilizing the Microsoft.StoreServices .NET library and sample

To help demonstrate the principles and flows outlined in this article review the Microsoft.StoreServices Sample. The sample uses the Microsoft.StoreServices library to manage authentication and make the calls to the Microsoft Store Services. The sample service itself has example logic for managing subscription products and provides a configuration guide to get it set up.

Subscription Product Types

Both Store-managed and Add-on subscription product types work with the Recurrence service to view and manage the user's subscription. For more information on each of these product types see Choosing the right product type

Querying for a users subscription

The purchase.mp.microsoft.com/v8.0/b2b/recurrences/query is the main endpoint to query for a user's subscription information. This endpoint reports both currently active and past subscription periods for the user. Additionally, it provides the subscriptionId required to make a change to the subscription and more detailed information to detect when a subscription is in the Grace and Dunning periods.

The Collections endpoints (B2bLicensePreview (v8) or PublisherQuery (v9)) will both return an active subscription for a user, but do not provide the level of detail and information that the Recurrence Query API does.

Understanding subscription start, renew, and expire dates

The StartTime date of a subscription will always be the date on which the active subscription started. If the subscription is set for auto-renew, the start date will remain the same but the expire dates will change as the subscription is renewed in the following months. If a subscription is canceled, expires, or is revoked a new subscription object will be created when the user purchases the subscription again. This new active subscription period will have the StartTime of the day they activated or purchased the new subscription.

The subscription periods within the Microsoft Store are normally configured as a quantity of months. For example, 1 month, 3 months, or 12 months. When a user purchases a one month subscription, the StartTime will be midnight UTC (00:00:00) of the day they started the subscription. ExpirationTime will then be the the number of months (not days) added to the StartTime minus one second (23:59:59 UTC).
This is so that the subscription will expire just before midnight UTC.

However, some months have a different number of days creating a conflict with subscriptions starting on a 29th, 30th, or 31st of a month.
If the user's StartTime falls on any of these days, the ExpirationTime is modified to be 23:59:59 UTC the last day of the expiring month. This way, the renewal date will always be midnight UTC (00:00:00) the first day of the month going forward and the ExpirationTime will always be 23:59:59 UTC the last day of the month.

Example start, renew, and expire date behavior of a one month subscription

Purchase Date	StartTime	ExpireTime	Auto Renew Date	Active Days
2023-02-27T12:00:00Z	2023-02-27T00:00:00Z	2023-03-26T23:59:59Z	2023-03-27T00:00:00Z	28
2023-03-27T12:00:00Z	2023-03-27T00:00:00Z	2023-04-26T23:59:59Z	2023-05-27T00:00:00Z	31
2023-03-29T12:00:00Z	2023-03-29T00:00:00Z	2023-04-30T23:59:59Z	2023-05-01T00:00:00Z	32
2023-04-29T12:00:00Z	2023-04-29T00:00:00Z	2023-05-31T23:59:59Z	2023-06-01T00:00:00Z	33
2023-04-30T12:00:00Z	2023-04-30T00:00:00Z	2023-05-31T23:59:59Z	2023-06-01T00:00:00Z	32
2024-02-27T12:00:00Z	2024-02-27T00:00:00Z	2024-03-26T23:59:59Z	2024-03-27T00:00:00Z	29 (Leap Year)

Understanding Grace and Dunning states

If a user is enrolled in auto-renew for their subscription, the Microsoft Store will attempt to charge the payment instrument on the user's account on their subscription's ExpirationTime value. If the payment is unable to be fulfilled, their subscription is not canceled but goes through the Grace and then Dunning states as the Microsoft Store tries to resolve and retry the payment. During both the Grace and Dunning periods, the subscriptions status will show as InDunning. When integrating a subscription product with your services, you should understand and implement checks to identify when a user is in the Grace or Dunning period and take appropriate action based on the information below.

To properly set an account into each of these states for testing, see Testing subscription products.

Grace period

The Grace period is a set time that the user should still receive subscription benefits even though they are now past the ExpirationTime of their paid subscription. During this time, the Microsoft Store will continue to attempt to auto-renew with the user's payment instrument. This allows the user time to resolve an expired credit card, or add more funds to their account if needed without losing the subscription benefits.

Once the payment instrument is fixed and the auto-renew transaction completed, the Grace time used is subtracted from the user's next subscription period. Ex: The subscription time is for a 30 day period and the user's account spent 3 days in Grace while their payment instrument was fixed. When the auto-renew transaction succeeds, it will be for another 30 day period. But the used 3 days of Grace will be removed from their new ExpirationTime so their subscription will now expire in 27 days from the renewal transaction. This results in the new ExpirationTime being 30 days from the previous ExpirationTime so the user did not receive any free time because they went into the Grace period.

Because both the Grace and Dunning periods share the same status (InDunning) your service must check the current UTC time against the ExpirationTimeWithGrace value to determine if the user is in the Grace period or not. During this time, you can also message the user to notify them that there may be an issue with their subscription renewal and to check their Microsoft Account Service & Subscriptions page.

If the auto-renew is not resolved by the ExpirationTimeWithGrace, the account goes into the Dunning period.

Dunning period

The Dunning period is a set time after the user's Grace period has run out, and the users should not longer be receiving benefits of the subscription on their account. During the Dunning period the Microsoft Store will continue attempts to charge the user's account for a new subscription period. If the charge is successful, the full grace period time is subtracted from the user's next subscription period.

While in the Dunning period, the user will be unable to re-purchase or redeem the subscription by itself through the store. This ensures that the users can't just get free time by going into the Grace period and then starting a new subscription when Grace ends. Dunning is a much longer period of time than Grace, but if the payment is not completed by the end of Dunning the subscription will become inactive.

Changing a user's subscription

Besides querying for a user's subscription status, your services can also modify and change the user's subscription product on the user's behalf. The purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change endpoint allows your service to add time, cancel, refund, and disable auto-renew to a specific subscription. To call the Recurrence Change endpoint, you need to first have the recurrenceId value which is obtained from the purchase.mp.microsoft.com/v8.0/b2b/recurrences/query endpoint.

Here are some examples of how the Recurrence Change endpoint can be useful with your services:

Adding time to users' subscriptions who experienced a service downtime.
Integration with your Customer Service Support teams to help users with information on their subscription status, cancellations, etc.
Allow in-game UI to easily allow users to disable auto-renew or end their subscriptions.

Testing subscription products

The Recurrence Change endpoint can also be used for development and testing of your subscription products. The Extend operation will accept negative numbers of days to subtract from an active subscription on a test account. This allows you to subscribe a test account to the subscription and then remove days from the subscription to reach your desired testing status.

Testing Active, Inactive, and Canceled states

Testing the Active, Inactive, and Canceled states for a subscription can be done with a subscription set to a price of $0.00. Simply add the subscription to the test account to verify the Active state and use the Recurrence Change endpoint to disable auto-renew. Then use the Recurrence Change endpoint to cancel the subscription or subtract enough days so that the ExpirationTime is past the current UTC DateTime.

Testing Grace and Dunning states

To get a subscription account into the Grace and Dunning states the subscription must have a non-zero price and the account must be in a state where it cannot purchase that amount when the ExpirationTime passes. Currently the Microsoft Store does not have test payment instruments so the easiest way to setup an account is using pre-paid currency codes as follows:

Setup the subscription with a low price point such as $0.99 in your test environment.
Purchase an Xbox pre-paid gift card for $1.00 or $2.00 to cover the first subscription purchase (plus tax) but not the renewal.
Redeem the gift card on your test account.
Purchase the subscription on the test account.
Make sure auto-renew is enabled for the subscription but there are not enough funds to renew the subscription.
Use Recurrence Change to move the ExpirationTime of the subscription to be within the next 24 hours (see note below for why this is important).
Wait till ExpirationTime has passed naturally and show status of 'InDunning' (this may take up to 24 hours after the ExpirationTime).

To see the proper change from Grace, Dunning, and into Inactive you should also let the account naturally go through those steps without moving the ExpirationTime artificially.

Note

To properly get an account into the 'InDunning' state for Grace and Dunning periods, the account must pass the ExpirationTime and ExpirationTimeWithGrace dates naturally. When subtracting days from a test subscription, subtract just enough to have the ExpirationTime within the next 24 hours of the current UTC DateTime. Then let the account pass that DateTime naturally over the next 24 hours for the status to show 'InDunning'. If you move the ExpirationTime farther than the current UTC DateTime, the state will not change to 'InDunning' and the test values will be invalid for that account / subscription. The test account will also enter a state where you won't be able to properly test Grace and Dunning until the current subscription item is canceled and a new subscription is purchased on the account.

Share via