Migrate subscriptions to new commerce

Appropriate roles: Admin agent | Sales agent | Global admin


The new commerce experiences for license-based services include many new capabilities and are available to all Cloud Solution Provider (CSPs). For more information, see new commerce experiences overview.

Ineligible subscriptions

Not all subscriptions are eligible for migration at this time. The following categories of subscriptions are currently ineligible:

  • Subscriptions within the first month of service since purchase (this check is only in Production; it isn't applied in Sandbox to aid effective testing).

  • Subscriptions within the last 24 hours will only be blocked if purchaseFullTerm is false. If purchaseFullTerm is true the migrations will be allowed in the last 24 hours.

  • Inactive subscriptions (no changes in service will occur if a subscription is inactive)

  • Trial subscriptions (no monetary benefit or implications; expectation will be to let trials run their course in legacy)

  • Subscriptions with promotions (promotions in New commerce Experience (NCE) are independent of those promotions in legacy)

  • Subscriptions for Gov, Edu, or Nonprofit audiences (the mapping of qualified offers from legacy to NCE isn't supported)

  • Retired or deprecated subscriptions (for these subscriptions, there won't be a like to like offer existing in New commerce)

  • Subscriptions without a corresponding offer available in New commerce; check the License-Based Services Cloud Reseller Offer Matrix tab labeled "NCE Mapping" to view viable migration mappings

Migrations of the aforementioned mentioned subscriptions are out of scope for this feature, and a single subscription will be the unit of migration, via the available APIs. Additionally, separate from the subscription ineligibility criteria listed, migration will be blocked if a subscription being migrated is in a processing state (such as migration for that subscription having already been initiated), if a migration request is passed in with an unsupported term and billing combo, if a partner has an incomplete Partner Profile, or if the subscription has an invalid Partner ID on record.

Suspending a legacy subscription during migration

Intended migration behavior is for the legacy subscription to only be suspended once a successful path to New commerce is provisioned for the subscription. This action will prevent loss of service if there are any blockers following a Partner initiating migration of a subscription. Additionally, no double billing will occur for both the legacy and New commerce subscription. Once migration has been initiated, billing for the legacy subscription will be stopped to prevent any overlap with billing for the NCE subscription.

Updating term length, term duration, billing frequency, and seat count upon migration

A subscription's remaining term, overall term length, billing frequency, and seat will remain the same in New commerce post-migration as those respective attributes of the traditional license-based subscription unless otherwise specified by a partner. The capability to update these values upon migration is available both in the Partner Center UX and via the "CreateMigration" API.

Configuring term and billing frequency

Options for configuring term and billing frequency can include the options below.

Migrate with the same term length and end date from legacy (default)

  • If a legacy subscription has a one-year term length and is in month seven of the term upon migration, it will have five remaining months of the term once migrated to NCE

Begin a new term upon migration; can specify new term length (for example, three years, one year, one month)

  • If a legacy subscription has a one-year term length and is in month seven of the term upon migration, it will start a new term in NCE, regardless of how "far along" it was in legacy.

Switch term length (for example, annual to monthly) without beginning a new term upon migration

  • If a legacy subscription has a one-year term length that ends on February 10, 2022, and a Partner chooses to migrate on November 17, 2021 without starting a new term but with switching to a monthly term, the new renewal date or "end of term" will be set to December 10, 2021. Since the partner chooses to migrate from annual to monthly the end of term will be set to terminate within the following month.

Billing frequency for the subscription may also be configured to other New commerce supported options, such as switching from annual to monthly billing.

Cancelling subscriptions or decreasing licenses

Newly migrated subscriptions will follow the same cancellation policy as new purchases in New commerce Experience.

Migrating subscriptions with add-ons

As of March 2022, migration of subscriptions with add-ons has been enabled via the Partner Center APIs and UX.

A base subscription and all of its active add-ons must migrate to New commerce together, as a bundle. For a subscription with add-ons to be eligible for migration, the subscription and all its add-ons must have corresponding offers in New commerce. If a subscription has multiple add-ons, and one add-on is ineligible to migrate, the subscription and all add-ons cannot migrate. Post-migration, the migrated add-ons will display as independent add-ons in NCE.

A partner can elect to make changes to the subscription terms, seat counts and billing frequency of the base subscription and the add-ons. Edited values are independent of each subscription (base subscription or add-on subscription) in the bundle being migrated. If no changes are elected, in NCE, both the base subscription and its add-ons default to the quantity, billing frequency, term duration, and term end date each respective SKU had in legacy.

Because both the base subscription and add-on subscription(s) are being migrated together as a bundle, the purchase of a new add-on subscription will result in migration ineligibility for the next 30 days (post add-on purchase) of the whole bundle, even if the base subscription is greater than 30 days old. Each subscription in the bundle being migrated will be validated for eligibility individually, and this includes the 30 day purchase check on each subscription. If one subscription is ineligible for migration, the entire bundle cannot migrate.

At this time, you can't migrate add-ons independently (without the base subscription) to New commerce. However, nested add-ons (add-ons with add-ons of their own) are eligible to migrate, and each of these add-ons will appear as independent in NCE.

Promotions on migrated subscriptions

Migration doesn't affect an offer's eligibility to qualify for an available promotion. If the remaining term of the traditional license-based subscription isn't updated upon migration, and the New commerce Experience subscription is eligible for a promotion, the promotion will be applied to the remainder of the NCE subscription's term.

Expected migration timelines

The time a migration request takes to complete varies depending on factors such as attributes edited within the request and the quantity of requests being submitted at a time through Partner Center. Migration usually takes from zero to six hours, but in some cases migrations take up to seven days.

Partners can view the migration status in the Partner Center portal via the customer’s Subscriptions page or by calling the Get a new commerce subscription migration API.

When a migration request is submitted, the legacy subscription will be set to a suspended state when the migration begins. A suspended legacy subscription with no corresponding NCE offer will be visible on the subscription list. Additionally, the Get a new commerce subscription migration API request will return a migration status of “Failed” for migrations affected by this error. A partner’s next steps are determined by the status of the legacy subscription:

  • Legacy subscription still “Active”: Legacy subscriptions that are still active in a failed migration state is allowed to be retried.
  • Legacy subscriptions that are “Suspended”. Migration status of “Failed” where the legacy subscription is suspended are still being processed by the system, partners should let the migration as Microsoft will diagnose and correct the issue if needed during the seven day window. Microsoft will correct this issue within seven days of the initial migration request.

Migrations with “Failed” status with the legacy subscription in a suspended legacy subscription with no NCE subscription creation may take up to seven days from the time of the initial migration request for Microsoft to address the issue. Microsoft will either correct the error and complete migration (successfully creating the migration’s corresponding NCE subscription) or will revert the migration on the seventh day. If the migration is successfully completed by Microsoft within seven days, no further action is required by the partner. If the migration is reverted, the legacy subscription will be active again; retry migration in this scenario.

During the period where the legacy subscription is suspended without a corresponding NCE offer created, no service loss will occur. The start of billing for the NCE subscription will align with the date the New commerce subscription was created if Microsoft successfully completes migration. The created New commerce subscription will retain the pricing and promotion specified at the time the migration request was created.

If the legacy subscription is reverted to a pre-migration state (effectively rolling back the migration request), billing of the legacy subscription will resume when the legacy subscription active again; no charges will be made for the period where the legacy subscription was suspended without a corresponding NCE subscription created.

Migration of SMB SKUs

Customers who have SMB SKUs are subject to a 300-seat limit when migrating their subscription from legacy to seat-based offers for new commerce.

A partner can migrate a customer’s SMB subscription with 200-seats successfully. But if the customer has another 200-seats on the same SMB SKU they want to migrate, the system will block the migration because the transaction exceeds the 300-seat limit. In this case, the partner can adjust the seat count of the second SKU they would like to migrate from 200 to 100 (or lower to fall within the SMB seat limits) successfully.

If a partner submits a migration request at the same time for two SMB SKUs with 200 seats, one migration request will go through and the other request will fail. In this case, the partner would adjust the second SKU they would like to migrate from 200 to 100 (or lower to fall within the SMB seat limits) successfully.

Migration history

Some migration details, such as start and completion time of migration, can be accessed using the new Get a new commerce subscription migration API and MigrationID field in the APIs. At Partner Center, the Subscription ID from which the new NCE subscription migrated from is visible at the top of the details page, which can be accessed when selecting the subscription on the customer’s “Subscriptions” page.

Additionally, when clicking upon the migrated New commerce subscription in Partner Center (from the customer's subscriptions list), Partners are able to view a detailed log of migration events under the Migration Activity header that may include the status of the following migration activities:

  • MigrationStarted: time migration request was submitted
  • NewCommerceSubscriptionCreated: subscription created subscription ID
  • NewCommerceSubscriptionProvisioned: NCE subscription's service has been provisioned
  • MigrationCompleted: indicates migration was successful and NCE subscription can now be managed
  • MigrationFailed: migration was unsuccessful; service will not be lost and documented migration failure timelines are applicable

These migration events are also accessible via the GetMigrationEvents API.


The ability to see migration activity and events is a new feature. Any subscriptions migrated prior to June 22, 2022 will not have migration events recorded. This feature does not retroactively record migration events for subscriptions migrated prior to this date.

Bulk migration

In the case where a Partner is trying to migrate a customer's eligible subscriptions to NCE, the outlined steps may be taken:

  1. Select a customer to migrate the subscriptions.
  2. Call the Get a list of subscriptions API to receive a collection of the customer’s subscriptions by customer-tenant-id. Query parameter for Order ID is optional.
  3. Call the Validate a subscription for migration API to check the migration eligibility.
  4. Go through the collection of subscriptions and call the Create a New commerce migration API with each subscription-id. This action will check for migration eligibility and migrate the subscription if eligible.
  5. To check for the migration eligibility call the Get a New commerce subscription migration API after going through the Subscription collection. Subscriptions that have been successfully migrated will be populated with migratedFromSubscriptionID attribute. The migrationId provided by the CreateMigration response will also facilitate tracking the progress of the migrations when used in the Get a New commerce subscription migration API API request. The unit of migration is a single subscription, but this can be scaled to meet requirements of bulk migration scenarios.

Mapping legacy offers to new commerce experience

To view a mapping matrix of legacy to new commerce experience offers and determine the correct migration mapping for a specific legacy offer, complete the steps below.

  1. Go to the “Pricing | Price lists” page in Partner Center.
  2. Download the legacy Price Sheet “License-based pricing”.
  3. Download the legacy OLM file “Cloud Reseller offer matrix,” which has the mapping between legacy and new commerce in the first section for “License-based services” Cloud Reseller offer matrix.
  4. Download the legacy Price List through the API or the Partner Center UX.
  5. In the offer matrix file, select the tab that is named NCE Mapping.
  6. Map the Offer ID from the legacy price list to the Durable offer ID in the legacy offer matrix file in the NCE Mapping tab to determine the Modern Product / SKU ID to find the “Modern Product ID / SKU ID” in column Q.

Not all offers are migratable to NCE (e.g. offers such as legacy Azure Information Protection Premium P1 do not have an equivalent corresponding offers in NCE that can be migrated to).

Migration, transition, conversion, and upgrade

In Partner Center, migration into New commerce refers to the moving of subscriptions from the traditional licensed-based commerce into the New commerce Experience. This may be confused with other action terms in Partner Center, such as transition, conversion, and upgrade.

Upgrades and conversions are considered types of subscription transitions.

Transitions are used to upgrade a customer's new commerce subscription to a target subscription or convert a NCE trial to a paid subscription. The key difference between transitions and migrations is that migrating a subscription moves it from traditional commerce to the equivalent offer in New commerce Experience. Unlike transitions, migration can't be utilized to change between unequal subscriptions (such as an upgrade or conversion action).

Previous new commerce milestones

Effective March 10, 2022, legacy CSP commercial seat-based offers with equivalent new commerce offers will no longer be available for new orders on the legacy platform.

The price list will contain a new value within the A, C, D, and U column, flagging the offers with “DEPR” for retired or no-longer-supported offers. As of March 1, 2022, the offer matrix (OLM) will contain the list of offers that will be retired in a new sheet entitled “Legacy Deprecated.” On April 1, 2022, the price list will go out with offers that have been blocked for new purchases marked with “DEPR,” and pricing will continue to show up for these offers. Offers that are no longer available for purchase in legacy CSP won’t be discoverable via the Partner Center catalog and will be removed from the monthly CSP price lists.

Existing legacy subscriptions will still have the options for the partner to add or remove seats, purchase add-ons, upgrade the subscription through the subscription term, and convert from trial to paid, regardless of the blocking of new commerce purchases from March 10, 2022.

Additionally, the error messaging of Create Order, Create Cart, and Update Cart APIs will reflect available New commerce offers when a partner tries to purchase a blocked legacy offer. If an equivalent NCE offer is available for the blocked legacy offer that was attempted for purchase, the NCE offer's product ID, SKU ID, and availability ID will be provided to the partner through the API message. Note that availabilities may expire, and the provided availability ID may no longer be valid if there's a wait time between the partner receiving the error message and attempting to purchase in New commerce.