Transition API

Use the Transition API to transition your legacy Microsoft product subscriptions to New Commerce Experience (NCE) product subscriptions. You can schedule a legacy subscription to transition to NCE at renewal along with updates to quantity, termDuration ,and billingCycle. You can also track the progress of the transition using the API.

Prerequisites

• Create an API client for non-interactive applications. See Create API clients for non-interactive applications.
• Identify the target legacy subscriptions that you want to transition. Use one of the following:
  • List all subscriptions, see list-all-subscriptions.
  • List all subscriptions for a company.
  • Query the Microsoft Partner Center

To start the transition,

1. Call the transition API to start transition
2. Setup API Authorization
3. Setup API Headers
4. Call transition API

The Transition API allows requests to transition subscriptions at tenant or subscription level. To ensure that valid requests are sent for an authorized partner, the partner mentioned in the URL path should be consistent with Oauth2 ROLE_PARTNER, which avoids transitioning subscriptions belonging to other partners.

API Signature

Method: POST URL - {marketplace-base-url}/api/microsoft/v1/nce/transitions/{partner}/schedule

Authorization - Oauth2 ROLE\_PARTNER

Request payload schema

The following schema should be followed in the request body:

Request Payload Schema

{
 "tenantIds": [

{

"tenantId": "",

"subscriptions": [

{

"subscriptionId": "",

"termDuration": "P1M",

"billingCycle": "Monthly",

"quantity" : 7,

"productId" : 32825

 }]}

]}

The following table details each field in the schema:

Field	Value Type	Required	Description
tenantId	string	Y	The Microsoft tenant identifier that indicates which subscription requires validation for migration. If no subscriptions are provided, the API will trigger transition for all marketplace licenses based on active subscriptions for a given Tenant ID.
subscriptions	list	N	A subscription object that indicates which subscription requires migration.
subscriptionID	string	Y	A subscription identifier that indicates which subscription requires migration.
termDuration	string:P1M,P1Y,P3Y	N	The term duration for the subscription.
billingCycle	string:MONTHLY,ANNUAL,ONE_TIME,TRIENNIAL	N	The billing cycle for the subscription.
quantity	int	N	Indicates whether or not to change the quantity of new NCE subscriptions after renewal.
productID	long	N	The productID represents the ID displayed on the product dashboard. Specify productID if there are multiple product profiles that contain editions with the same edition code.

For the payload, you can choose to transition all the valid subscriptions under a tenant or only some of them. You can also transition subscriptions belonging to multiple tenants as long as they belong to the same partner.

Here are some sample request payloads for different scenarios:

Option 1: Transition some subscriptions of a specific tenant:

{

"tenantIds": [

{

"tenantId": "1c70901a-b43f-44a9-9913-05edde384eb2",

"subscriptions": [

{

"subscriptionId": "7633755a-3334-42c8-8347-e0db8e02a7b7",

"termDuration": "P1Y",

"billingCycle": "Monthly"

},
{

"subscriptionId": "37bab9b4-67a6-42c4-b383-adfa114432d1",

"termDuration": "P1Y",

"billingCycle": "Monthly",

"productId" : 32825

}]}

Option 2: Transition all valid subscriptions of a specific tenant

{

"tenantIds": [

{

"tenantId": "1c70901a-b43f-44a9-9913-05edde384eb2"

}]}

Option 3: Transition some subscriptions of multiple tenants

{

"tenantIds": [

{

"tenantId": "1c70901a-b43f-44a9-9913-05edde384eb2",

"subscriptions": [

{

"subscriptionId": "7633755a-3334-42c8-8347-e0db8e02a7b7",

"termDuration": "P1Y",

"billingCycle": "Monthly",

"quantity" : 10

},

{

"subscriptionId": "37bab9b4-67a6-42c4-b383-adfa114432d1",

"termDuration": "P1Y",

"billingCycle": "Monthly",

"quantity" : 10

}

]

},

{

"tenantId": "53bf2bbc-17cc-4797-bd85-956831cdb4a0",

"subscriptions": [

{

"subscriptionId": "332f2f10-8add-43e2-a5f9-b63dbc4efc53",

"termDuration": "P1M",

"billingCycle": "Monthly",

"quantity" : 10

},

{

"subscriptionId": "be3e7668-29b3-486f-a345-6e83ea09889d",

"termDuration": "P1M",

"billingCycle": "Monthly",

"quantity" : 7

}]

}

]}

To check the transition progress

1. Call transition API to check transition status
2. Setup API Authorization
3. Setup API Headers
4. Call status check API

Use the nceSubscriptionId field in the API response body to match the new subscriptions to the legacy subscriptions and to check which subscriptions were transitioned successfully.

After the transition is complete, check transitioned subscriptions on the AppDirect marketplace. Look at the company page and check if the new NCE product is provisioned and the legacy subscription is canceled.

Search for a specific product using its product name on the Orders page at Manage > Marketplace > Dashboard > ** BILLING | Orders. You can also check your transitioned subscription on the Microsoft Partner Center.

Limitations:

• This transition API does not support add-ons.
• Legacy subscriptions without contract cannot be scheduled for transition at renewal.
• Discounts won't be applied on subscriptions scheduled for transition.
• Further changes to pricing, edition, or quantity is blocked when a subscription is scheduled for transition.
• A maximum of 100 transitions can be sent to Microsoft in a five minute period.