Enable subscription add-ons for your app

Important

Currently, the ability to create subscription add-ons is only available to developers who are participating in an early adoption program. We will make subscription add-ons available to all developer accounts in the future, and we are making this preliminary documentation available now to give developers a preview of this feature.

Your Universal Windows Platform (UWP) app can offer in-app purchases of subscription add-ons to your customers. You can use subscriptions to sell digital products in your app (such as app features or digital content) with automated recurring billing periods.

Note

To enable the purchase of subscription add-ons in your app, your project must target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio (this corresponds to Windows 10, version 1607), and it must use the APIs in the Windows.Services.Store namespace to implement the in-app purchase experience instead of the Windows.ApplicationModel.Store namespace. For more information about the differences between these namespaces, see In-app purchases and trials.

Feature highlights

Subscription add-ons for UWP apps support the following features:

  • You can choose from subscription periods of 1 month, 3 months, 6 months, 1 year, or 2 years. Some apps can also use a 6-hour subscription period for testing purposes only.
  • You can add free trial periods of 1 week or 1 month to your subscription.
  • The Windows SDK provides APIs you can use in your app to get info about available subscription add-ons for the app and enable the purchase of a subscription add-on. We also provide REST APIs you can call from your services to manage subscriptions for a user.
  • You can view analytic reports that provide the number of subscription acquisitions, active subscribers, and canceled subscriptions in a given time period.
  • Customers can manage their subscription on the http://account.microsoft.com/services page for their Microsoft account. Customers can use this page to view all of the subscriptions they have acquired, cancel a subscription, and change the form of payment that is associated with their subscription.

Steps to enable a subscription add-on for your app

To enable the purchase of subscription add-ons in your app, follow these steps.

  1. Create an add-on submission for your subscription in the Dev Center dashboard and publish the submission. As you follow the add-on submission process, pay close attention to the following properties:

    • Product type: Make sure you select Subscription.

    • Subscription period: Choose the recurring billing period for your subscription. You cannot change the subscription period after you publish your add-on.

      Each subscription add-on supports a single subscription period and trial period. You must create a different subscription add-on for each type of subscription you want to offer in your app. For example, if you wanted to offer a monthly subscription with no trial, a monthly subscription with a one-month trial, an annual subscription with no trial, and an annual subscription with a one-month trial, you would need to create four subscription add-ons.

      Note

      If you are in the process of implementing the in-app purchase experience for your subscription, we recommend that you create a test add-on with the For testing only – 6 hours subscription period to help you test the experience. You can choose this test period only if you select one of the Hidden in the Store visibility options for your test add-on.

    • Trial period: Consider choosing a 1 week or 1 month trial period for your subscription to enable users to try your subscription content before they buy it. You cannot change or remove the trial period after you publish your subscription add-on.

      To acquire a free trial of your subscription, a user must purchase your subscription through the standard in-app purchase process, including a valid form of payment. They are not charged any money during the trial period. At the end of the trial period, the subscription automatically converts to the full subscription and the user's payment instrument will be charged for the first period of the paid subscription. If the user chooses to cancel their subscription during the trial period, the subscription remains active until the end of the trial period.

      Note

      Some trial durations are not available for all subscription periods.

    • Visibility: If you creating a test add-on that you will only use to test the in-app purchase experience for your subscription, we recommend that you select one of the Hidden in the Store options. Otherwise, you can select the best visibility option for your scenario.

    • Pricing: Choose the price of your subscription in this section. You cannot raise the price of the subscription after you publish the add-on (however, you can lower the price later).

      Important

      By default, when you create any add-on the price is initially set to Free. Because you cannot raise the price of a subscription add-on after you complete the add-on submission, be sure to choose the price of your subscription here.

  2. In your app, use APIs in the Windows.Services.Store namespace to confirm whether the current user has already acquired your subscription add-on and then offer it for sale to the user as an in-app purchase. See the code examples in this article for more details.

  3. Test the in-app purchase implementation of your subscription in your app. You'll need to download your app once from the Store to your development device to use its license for testing. For more information, see our testing guidance for in-app purchases.

    Note

    If your app has access to the For testing only – 6 hours subscription period, we recommend that you create a test add-on with this period to help you test the experience. You can choose this test period only if you select one of the Hidden in the Store visibility options for your test add-on.

  4. Create and publish an app submission that includes your updated app package, including your tested code. For more information, see App submissions.

Code examples

The code examples in this section demonstrate how to use the APIs in the Windows.Services.Store namespace to get info about subscription add-ons for the current app and request the purchase a subscription add-on on behalf of the current user.

These examples have the following prerequisites:

  • A Visual Studio project for a Universal Windows Platform (UWP) app that targets Windows 10 Anniversary Edition (10.0; Build 14393) or a later release.
  • You have created an app submission in the Windows Dev Center dashboard and this app is published in the Store. You can optionally configure the app so it is not discoverable in the Store while you test it. For more information, see the testing guidance.
  • You have created a subscription add-on for the app in the Dev Center dashboard.

The code in these examples assumes:

  • The code runs in the context of a Page that contains a ProgressRing named workingProgressRing and a TextBlock named textBlock. These objects are used to indicate that an asynchronous operation is occurring and to display output messages, respectively.
  • The code file has a using statement for the Windows.Services.Store namespace.
  • The app is a single-user app that runs only in the context of the user that launched the app. For more information, see In-app purchases and trials.
Note

If you have a desktop application that uses the Desktop Bridge, you may need to add additional code not shown in these examples to configure the StoreContext object. For more information, see Using the StoreContext class in a desktop application that uses the Desktop Bridge.

Get info about subscription add-ons for the current app

This code example demonstrates how to get info for the subscription add-ons that are available in your app. To get this info, first use the GetAssociatedStoreProductsAsync method to get the collection of StoreProduct objects that represent each of the available add-ons for the app. Then, get the StoreSku for each product and use the IsSubscription and SubscriptionInfo properties to access the subscription info.

private StoreContext context = null;

public async void GetSubscriptionsInfo()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // Subscription add-ons are Durable products.
    string[] productKinds = { "Durable" };
    List<String> filterList = new List<string>(productKinds);

    workingProgressRing.IsActive = true;
    StoreProductQueryResult queryResult =
        await context.GetAssociatedStoreProductsAsync(productKinds);
    workingProgressRing.IsActive = false;

    if (queryResult.ExtendedError != null)
    {
        // The user may be offline or there might be some other server failure.
        textBlock.Text = $"ExtendedError: {queryResult.ExtendedError.Message}";
        return;
    }

    foreach (KeyValuePair<string, StoreProduct> item in queryResult.Products)
    {
        // Access the Store product info for the add-on.
        StoreProduct product = item.Value;

        // For each add-on, the subscription info is available in the SKU objects in the add-on. 
        foreach (StoreSku sku in product.Skus)
        {
            if (sku.IsSubscription)
            {
                // Use the sku.SubscriptionInfo property to get info about the subscription. 
                // For example, the following code gets the units and duration of the 
                // subscription billing period.
                StoreDurationUnit billingPeriodUnit = sku.SubscriptionInfo.BillingPeriodUnit;
                uint billingPeriod = sku.SubscriptionInfo.BillingPeriod;
            }

        }
    }
}

Purchase a subscription add-on

This example demonstrates how to use the RequestPurchaseAsync method of the StoreProduct class to purchase a subscription add-on. This example assumes that you already know the Store ID of the subscription add-on you want to purchase.

private StoreContext context = null;

public async void PurchaseSubscription(string storeId)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // First, get the StoreProduct object for the subscription add-on. This example
    // assumes you already know the Store ID for the add-on and you have passed
    // it to this method.
    string[] productKinds = { "Durable" };
    List<String> filterList = new List<string>(productKinds);
    string[] storeIds = new string[] { storeId };

    workingProgressRing.IsActive = true;
    StoreProductQueryResult queryResult =
        await context.GetStoreProductsAsync(filterList, storeIds);
    workingProgressRing.IsActive = false;

    StoreProduct mySubscription = queryResult.Products.FirstOrDefault().Value;

    // Make sure the user has not already acquired the subscription add-on, then 
    // offer it for purchase to the user.
    if (!mySubscription.IsInUserCollection)
    {
        workingProgressRing.IsActive = true;
        StorePurchaseResult result = await mySubscription.RequestPurchaseAsync();
        workingProgressRing.IsActive = false;

        // Capture the error message for the operation, if any.
        string extendedError = string.Empty;
        if (result.ExtendedError != null)
        {
            extendedError = result.ExtendedError.Message;
        }

        switch (result.Status)
        {
            case StorePurchaseStatus.Succeeded:
                textBlock.Text = "The purchase was successful.";
                break;

            case StorePurchaseStatus.NotPurchased:
                textBlock.Text = "The purchase did not complete. " +
                    "The user may have cancelled the purchase. ExtendedError: " + extendedError;
                break;

            case StorePurchaseStatus.NetworkError:
                textBlock.Text = "The purchase was unsuccessful due to a network error. " +
                    "ExtendedError: " + extendedError;
                break;

            case StorePurchaseStatus.ServerError:
                textBlock.Text = "The purchase was unsuccessful due to a server error. " +
                    "ExtendedError: " + extendedError;
                break;

            default:
                textBlock.Text = "The purchase was unsuccessful due to an unknown error. " +
                    "ExtendedError: " + extendedError;
                break;
        }
    }
}

Manage subscriptions from your services

After your updated app is in the Store and customers can buy your subscription add-on, you may have scenarios where you need to manage the subscription for a customer. We provide REST APIs you can call from your services to perform the following subscription management tasks:

Cancellations

Customers can use the http://account.microsoft.com/services page for their Microsoft account to view all of the subscriptions they have acquired, cancel a subscription, and change the form of payment that is associated with their subscription. When a customer cancels a subscription using this page, they continue to have access to the subscription for the duration of the current billing cycle. They do not get a refund for any part of the current billing cycle. At the end of the current billing cycle, their subscription is deactivated.

You can also cancel a subscription on behalf of a user by using our REST API to change the billing state of a subscription for a given user.

Unsupported scenarios

The following scenarios are not currently supported for subscription add-ons.

  • Selling subscriptions to customers directly via the Store is not supported at this time. Subscriptions are available for in-app purchases of digital products only.
  • Customers cannot switch subscription periods using the http://account.microsoft.com/services page for their Microsoft account. To switch to a different subscription period, customers much cancel their current subscription and then purchase a subscription with a different subscription period from your app.
  • Tier switching is currently not supported for subscription add-ons (for example, switching a customer from a basic subscription to a premium subscription with more features).
  • Sales and promotional codes are currently not supported for subscription add-ons.