Convert a trial subscription to paid using Partner Center APIs

Article
09/22/2023

Note

These steps aren't applicable for New Commerce Products. Refer to Transition a new commerce subscription documentation for converting New Commerce trials to paid subscriptions

You can convert a trial subscription to paid.

Prerequisites

Credentials as described in Partner Center authentication. This scenario supports authentication with App+User credentials only.
A customer ID (customer-tenant-id). If you don't know the customer's ID, you can look it up in Partner Center by selecting the Customers workspace, then the customer from the customer list, then Account. On the customer's Account page, look for the Microsoft ID in the Customer Account Info section. The Microsoft ID is the same as the customer ID (customer-tenant-id).
A subscription ID for an active trial subscription.
An available conversion offer.

Convert a trial subscription to a paid subscription through code

To convert a trial subscription to a paid one, you must first obtain a collection of the trial conversions available. Then, you must choose the conversion offer that you want to purchase.

The conversion offers will specify a quantity that defaults to the same number of licenses as the trial subscription. You can change this quantity by setting the Quantity property to the number of licenses that you want to purchase.

Note

Regardless of the number of licenses purchased, the subscription ID of the trial is reused for the purchased licenses. As a result, the trial in effect disappears and is replaced by the purchase.

Use the following steps to convert a trial subscription through code:

Get an interface to the subscription operations available. You must identify the customer and specify the subscription identifier of the trial subscription.
```
var subscriptionOperations = partnerOperations.Customers.ById(customerId).Subscriptions.ById(subscriptionId);
```
Get a collection of the available conversion offers. For more information and details on the request/response for this method, see Get a list of trial conversion offers.
```
var conversions = subscriptionOperations.Conversions.Get();
```
Choose a conversion offer. The following code chooses the first conversion offer in the collection.
```
var selectedConversion = conversions.Items.ToList()[0];
```
Optionally, specify the number of licenses to purchase. The default is the number of licenses in the trial subscription.
```
selectedConversion.Quantity = 10;
```

Call the Create or CreateAsync method to convert the trial subscription to paid.

var convertResult = subscriptionOperations.Conversions.Create(selectedConversion);

C#

To convert a trial subscription to a paid one:

Use the IAggregatePartner.Customers.ById method with the customer ID to identify the customer.
Get an interface to subscription operations by calling the Subscriptions.ById method with the trial subscription ID. Save a reference to the subscription operations interface in a local variable.
Use the Conversions property to obtain an interface to the available operations on conversions, and then call the Get or GetAsync method to retrieve a collection of available Conversion offers. You must choose one. The following example defaults to the first conversion available.
Use the reference to the subscription operations interface that you saved in a local variable and the Conversions property to obtain an interface to the available operations on conversions.
Pass the selected conversion offer object to the Create or CreateAsync method to attempt the trial conversion.

C# example

// IAggregatePartner partnerOperations;
// string customerId;
// string subscriptionId;

// Get subscription operations for the trial subscription.
var subscriptionOperations = partnerOperations.Customers.ById(customerId).Subscriptions.ById(subscriptionId);

// Get the available conversions.
var conversions = subscriptionOperations.Conversions.Get();

// If there are no conversions available, we&#39;re done.
// Otherwise, convert the trial to the first available conversion offer.
if (conversions.TotalCount <= 0)
{
    System.Console.WriteLine("This subscription has no conversions");
}
else
{
    // Default to the first conversion.
    var selectedConversion = conversions.Items.ToList()[0];

    // Convert the trial and return the result.
    var convertResult = subscriptionOperations.Conversions.Create(selectedConversion);
}

REST request

Request syntax

Method	Request URI
POST	{baseURL}/v1/customers/{customer-id}/subscriptions/{subscription-id}/conversions HTTP/1.1

URI parameter

Use the following path parameters to identify the customer and trial subscription.

Name	Type	Required	Description
customer-id	string	Yes	A GUID formatted string that identifies the customer.
subscription-id	string	Yes	A GUID formatted string that identifies the trial subscription.

Request headers

For more information, see Partner Center REST headers.

Request body

A populated Conversion resource must be included in the request body.

Request example

POST https://api.partnercenter.microsoft.com/v1/customers/0c39d6d5-c70d-4c55-bc02-f620844f3fd1/subscriptions/488745B5-2086-4912-802C-6ABB9F7C3638/conversions HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: bd0cde7f-ba87-4010-8a73-1190b641f2a4
MS-CorrelationId: 8daa6d54-72ab-4d6b-9c7d-9266d3734a47
X-Locale: en-US
Content-Type: application/json
Host: api.partnercenter.microsoft.com
Content-Length: 234
Expect: 100-continue

{
    "OfferId": "C0BD2E08-11AC-4836-BDC7-3712E744922F",
    "TargetOfferId": "031C9E47-4802-4248-838E-778FB1D2CC05",
    "OrderId": "D51A052E-043C-4A2A-AA37-2BB938CEF6C1",
    "Quantity": 25,
    "BillingCycle": "monthly",
    "Attributes": {
        "ObjectType": "Conversion"
    }
}

REST response

If successful, the response body contains a ConversionResult resource.

Response success and error codes

Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use a network trace tool to read this code, error type, and additional parameters. For the full list, see Partner Center error codes.

Response example

HTTP/1.1 200 OK
Content-Length: 211
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 8daa6d54-72ab-4d6b-9c7d-9266d3734a47
MS-RequestId: bd0cde7f-ba87-4010-8a73-1190b641f2a4
MS-CV: kW4GzmhvHEqCq1ls.0
MS-ServerId: 030020643
Date: Thu, 15 Jun 2017 23:10:40 GMT

 {
    "subscriptionId": "488745B5-2086-4912-802C-6ABB9F7C3638",
    "offerId": "C0BD2E08-11AC-4836-BDC7-3712E744922F",
    "targetOfferId": "031C9E47-4802-4248-838E-778FB1D2CC05",
    "attributes": {
        "objectType": "ConversionResult"
    }
}