Transition a subscription
Applies to: Partner Center | Partner Center operated by 21Vianet | Partner Center for Microsoft Cloud for US Government
Upgrades a customer's subscription to a specified target subscription.
Prerequisites
Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.
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).Two subscription IDs, one for the initial subscription and one for the target subscription.
GDAP roles
You'll need at least one of the following GDAP roles:
- Directory Reader or Global reader (upgrade only)
- Directory Writer (upgrade with license transfer)
C#
To upgrade a customer's subscription, first get that's customer's subscription. Then, obtain a list of upgrades for that subscription by calling the Upgrades property followed by the Get() or GetAsync() methods. Choose a target upgrade from that list of upgrades, and then call the Upgrades property of the initial subscription, followed by the Create() method.
// IAggregatePartner partnerOperations;
// string selectedCustomerId;
// string subscriptionIdForUpgrade;
// Upgrade targetOffer;
UpgradeResult upgradeResult = partnerOperations.Customers.ById(selectedCustomerId).Subscriptions.ById(subscriptionIdForUpgrade).Upgrades.Create(targetOffer);
Sample: Console test app. Project: PartnerSDK.FeatureSamples Class: UpgradeSubscription.cs
REST request
Request syntax
| Method | Request URI |
|---|---|
| GET | {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}/upgrades HTTP/1.1 |
| POST | {baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{id-for-target}/upgrades HTTP/1.1 |
URI parameter
Use the following query parameter to transition the subscription.
| Name | Type | Required | Description |
|---|---|---|---|
| customer-tenant-id | guid | Y | A GUID corresponding to the customer. |
| id-for-subscription | guid | Y | A GUID corresponding to the initial subscription. |
| id-for-target | guid | Y | A GUID corresponding to the target subscription. |
Request headers
For more information, see Partner Center REST headers.
Request body
None
Request example
GET https://api.partnercenter.microsoft.com/v1/customers/{customer-tenant-id}/subscriptions/{id-for-subscription}/upgrades HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
X-Locale: en-US
POST https://api.partnercenter.microsoft.com/v1/customers/{customer-tenant-id}/subscriptions/{id-for-target}/upgrades HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 750fd5ea-904b-4c3e-b476-60d0feacab0d
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
X-Locale: en-US
Content-Type: application/json
Content-Length: 1098
Expect: 100-continue
{
"TargetOffer":{
"Id":"796B6B5F-613C-4E24-A17C-EBA730D49C02",
"Name":"Office 365 Enterprise E3",
"Description":"The best plan for businesses that need full productivity, communication and collaboration tools with the familiar Office suite, including Office Online.",
"MinimumQuantity":1,
"MaximumQuantity":10000000,
"Rank":61,
"Uri":"/3c95518e-8c37-41e3-9627-0ca339200f53/Offers/796B6B5F-613C-4E24-A17C-EBA730D49C02",
"Locale":"en-us",
"Country":"US",
"Category":{
"Id":"Enterprise_Key",
"Name":"Enterprise",
"Rank":20,
"Locale":"en-us",
"Country":"US",
"Attributes":{
"ObjectType":"OfferCategory"
}
},
"PrerequisiteOffers":[],
"IsAddOn":false,
"IsAvailableForPurchase":true,
"Billing":"license",
"IsAutoRenewable":true,
"Product":{
"Id":"6fd2c87f-b296-42f0-b197-1e91e994b900",
"Name":"Office 365 Enterprise E3",
"Unit":"Licenses"
},
"UnitType":"Licenses",
"Links":{
"LearnMore":{
"Uri":"http://g.microsoftonline.com/0BXPS00en/1015",
"Method":"GET",
"Headers":[]
}
}
"Attributes":{
"ObjectType":"Offer"
}
},
"UpgradeType":1,
"IsEligible":true,
"Quantity":1,
"UpgradeErrors":[],
"Attributes":{
"ObjectType":"Upgrade"
}
}
REST response
If successful, this method returns an Upgrade result resource in the response body.
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 Error Codes.
Response example
HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
Date: Fri, 29 Jan 2016 20:42:26 GMT
{
"totalCount": 1,
"items": [{
"targetOffer": {
"id": "91FD106F-4B2C-4938-95AC-F54F74E9A239",
"name": "Office 365 Enterprise E1",
"description": "For businesses that need communication and collaboration tools and the ability to read and do lightweight editing of documents with Office Online.",
"minimumQuantity": 1,
"maximumQuantity": 10000000,
"rank": 48,
"uri": "/3c95518e-8c37-41e3-9627-0ca339200f53/Offers/91FD106F-4B2C-4938-95AC-F54F74E9A239",
"locale": "en-us",
"country": "US",
"category": {
"id": "Enterprise_Key",
"name": "Enterprise",
"rank": 20,
"locale": "en-us",
"country": "US",
"attributes": {
"objectType": "OfferCategory"
}
},
"prerequisiteOffers": [],
"isAddOn": false,
"isAvailableForPurchase": true,
"billing": "license",
"isAutoRenewable": true,
"isInternal": false,
"conversionTargetOffers": [],
"partnerQualifications": ["none"],
"product": {
"id": "18181a46-0d4e-45cd-891e-60aabd171b4e",
"name": "Office 365 Enterprise E1",
"unit": "Licenses"
},
"unitType": "Licenses",
"links": {
"learnMore": {
"uri": "http://g.microsoftonline.com/0BXPS00en/1013",
"method": "GET",
"headers": []
},
"self": {
"uri": "/offers/91FD106F-4B2C-4938-95AC-F54F74E9A239?country=US",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Offer"
}
},
"upgradeType": "upgrade_only",
"isEligible": false,
"quantity": 1,
"upgradeErrors": [{
"code": 2,
"description": "Subscription cannot be upgraded because the source subscription state is not active. Additional Details contains the current source subscription state.",
"attributes": {
"objectType": "UpgradeError"
}
}],
"attributes": {
"objectType": "Upgrade"
}
}],
"attributes": {
"objectType": "Collection"
}
}
HTTP/1.1 200 OK
Content-Length: 448
Content-Type: application/json
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
MS-RequestId: 750fd5ea-904b-4c3e-b476-60d0feacab0d
MS-CV: RnK86LBbDkWP/w2R.0
MS-ServerId: 102031201
Date: Fri, 29 Jan 2016 20:44:21 GMT
{
"sourceSubscriptionId":"896a2862-67e2-4f3d-bb3f-c50c42b5fad8",
"targetSubscriptionId":"2add8a55-454a-4ae5-a4c9-5107dc6e9768",
"upgradeType":1,
"upgradeErrors":[],
"licenseErrors":[],
"attributes":{
"objectType":"UpgradeResult"
}
}
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for