Managing subscription products from your service

For subscription products, use a back-end service to validate status and manage lifecycle operations. Using the Recurrence APIs gives your support and live-ops teams a reliable way to inspect, extend, or cancel subscriptions. This article explains how to use the Recurrence endpoints for those scenarios.

​

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.

• Microsoft.StoreServices (GitHub)
• Microsoft.StoreServices Sample (GitHub)

​

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 user’s subscription

Use purchase.mp.microsoft.com/v8.0/b2b/recurrences/query as the primary endpoint for subscription status. It returns active and historical subscription periods, plus the subscriptionId needed for change operations. It also includes the fields required to distinguish Grace and Dunning periods. Collections APIs (b2bLicensePreview (v8) and publisherQuery (v9)) can show active subscription entitlement but not the same recurrence detail.

​

Delay between satisfying entitlement checks on the client vs server-to-server

When you publish an update adding new items (satisfying entitlements) to a bundle, a delay exists between the visibility of the new items between the client and server-to-server API queries. This delay occurs because different store systems update their catalog caches at different intervals. When the change is published to the catalog, the local licensing services will usually get the updated info first and the caches used by publisherQuery within two to three hours after. Therefore, anticipate a few hours between client side APIs granting access and your server-to-server calls not reflecting ownership of the new items. The Recurrence service itself isn’t affected, only the publisherQuery or b2bLicensePreview endpoints querying for satisfying entitlements on the newly added items.

​

Understanding subscription start, renew, and expire dates

The StartTime date of a subscription is the date on which the active subscription started. If the subscription is set for auto-renew, the start date remains the same but the expired dates change as the subscription is renewed in the following months. If a subscription is canceled, expires, or revoked, a new subscription object is created when the user purchases the subscription again. The new active subscription period has 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 is midnight UTC (00:00:00) of the day they started the subscription. ExpirationTime is the number of months (not days) added to the StartTime minus one second (23:59:59 UTC).
This value is so that the subscription expires 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 is always midnight UTC (00:00:00) the first day of the month going forward and the ExpirationTime is always 23:59:59 UTC the last day of the month.

​

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

​

Understanding Grace and Dunning states

If an auto-renew payment fails at ExpirationTime, the subscription enters Grace, then Dunning if still unresolved. Both periods report status of InDunning, so determine the current period by comparing current UTC time to ExpirationTimeWithGrace. While a user’s subscription is in Grace or Dunning, you should notify users to check their billing status on Microsoft Account Service & Subscriptions. To properly set an account into each of these states for testing, see Testing subscription products.

​

Grace period

During Grace, keep subscription benefits enabled while the Store retries the renewal payment. If renewal succeeds, used Grace days are deducted from the next period. If payment isn’t resolved before ExpirationTimeWithGrace, the subscription moves to Dunning.

​

Dunning period

Dunning starts after Grace ends. Disable subscription benefits during this period. Users can’t repurchase or redeem the same subscription during Dunning. If payment remains unresolved through Dunning, the subscription becomes inactive.

​

Grace and Dunning lengths

​

Changing a user’s subscription

Your services can also modify subscriptions with purchase.mp.microsoft.com/v8.0/b2b/recurrences//change. Supported operations include adding days, disabling auto-renew, and canceling the subscription. Your service needs the recurrenceId (same value as id from RecurrenceQuery API and recurrenceData values from Collections query API) to operate on the user’s subscription. 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.
• In-game UI allowing users to change settings such as auto-renew or end their subscriptions.

​

Testing subscription products

The Recurrence Change API can also be used for testing. Extend accepts negative day values, letting you move a test subscription forward to target states.

​

Testing Active, Inactive, and Canceled states

When you test the Active, Inactive, and Canceled states for a subscription, you can use a base price of $0.00 on the subscription. Add the subscription to the test account to verify the Active state and use the Recurrence Change endpoint to disable auto-renewal. 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 test Grace and Dunning states, the subscription must have a non-zero price.
Additionally, the test account must be configured where follow-up payments wouldn’t succeed when the ExpirationTime passes. Currently the Microsoft Store doesn’t have test payment instruments so the easiest way to set up an account is using prepaid currency codes as follows:

1. Set up the subscription with a low price point such as $0.99 in your test environment.
2. Purchase an XBOX prepaid gift card for $1.00 or$2.00 to cover the first subscription purchase (plus tax) but not the renewal.
3. Redeem the gift card on your test account.
4. Purchase the subscription on the test account.
5. Make sure auto-renew is enabled for the subscription but there aren’t enough funds to renew the subscription.
6. Use Recurrence Change to move the ExpirationTime of the subscription to be within the next 24 hours (see the following note).
7. Wait for ExpirationTime to pass naturally and for status to show InDunning (can take up to 24 hours after ExpirationTime).

For accurate Grace -> Dunning -> Inactive behavior, let the account progress naturally after setting up the test.

​

See also

Commerce Overview Microsoft Store Service APIs purchase.mp.microsoft.com/v8.0/b2b/recurrences/query purchase.mp.microsoft.com/v8.0/b2b/recurrences//change Microsoft.StoreServices library (GitHub) Microsoft.StoreServices Sample (GitHub)