Upgrade Commerce 14 to Commerce 15

Why upgrade to Commerce 15

Commerce 15 aligns the commerce platform with CMS 13 and moves to .NET 10, bringing architectural improvements that affect how you build and deploy commerce solutions:

• CMS 13 compatibility — Commerce 14 is not compatible with CMS 13. If you are upgrading CMS, Commerce must follow
• .NET 10 runtime — Performance improvements, new language features, and continued LTS support
• Explicit package model — Commerce 15 moves away from metapackages to explicit NuGet references, giving you finer control over dependencies
• Content Graph integration — Built-in support for Optimizely Graph replaces older delivery mechanisms
• Visual Builder support — Commerce content types work with the CMS 13 Visual Builder experience

Before you start

What this upgrade involves

This upgrade touches three layers simultaneously:

Component	From	To
Commerce	14.15.3	15.0.0-preview1
CMS	12.31.2	13.0.0-preview4
.NET	8.0	10.0

Preview version warning

Commerce 15.0.0-preview1 and CMS 13.0.0-preview4 are pre-release versions. Do not use them in production. Use this guide for evaluation, testing, and preparing your upgrade plan. Commerce 15-compatible versions for popular add-ons will be released at a later date.

Prerequisites

You need the following before starting:

• Visual Studio 2022 with the .NET 10.0 SDK installed
• SQL Server (LocalDB or a full instance)
• A working Commerce 14/CMS 12 site (or use the empty template in Step 1 to create one)
• Familiarity with Optimizely Commerce architecture and NuGet package management

Upgrade steps

Step 1: Establish a baseline Commerce 14 site

If you do not have an existing Commerce 14 project to upgrade, create one from the template to use as a starting point:

dotnet new epi-commerce-empty --name CoCo14 --force

After creating the project:

1. Restore packages and build the project
2. Run the application (F5 in Visual Studio or dotnet run)
3. Register an admin user at https://localhost:5000/util/register
4. Log in at https://localhost:5000/util/login
5. Run the commerce migration at https://localhost:5000/episerver/commerce/migrate
6. Verify the admin UI loads at https://localhost:5000/episerver/cms

If you are upgrading an existing site, skip this step and proceed with your current project.

Step 2: Update the target framework

Open your .csproj file and change the target framework from .NET 8.0 to .NET 10.0:

<!-- Before -->
<TargetFramework>net8.0</TargetFramework>

<!-- After -->
<TargetFramework>net10.0</TargetFramework>

Step 3: Update NuGet package references

Commerce 15 and CMS 13 move from a metapackage model to explicit package references. This gives you visibility into every dependency and finer control over versions.

Replace your existing Commerce and CMS package references with explicit references.

Remove the old metapackages:

<!-- Remove these -->
<PackageReference Include="EPiServer.CMS" Version="12.31.2" />
<PackageReference Include="EPiServer.Commerce" Version="14.15.3" />

Add explicit Commerce 15 and CMS 13 packages:

<!-- Commerce 15 -->
<PackageReference Include="EPiServer.Commerce" Version="15.0.0-preview1" />

<!-- CMS 13 (all version 13.0.0-preview4) -->
<PackageReference Include="EPiServer.OptimizelyIdentity" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.UI.AspNetIdentity" Version="13.0.0-preview4" />
<PackageReference Include="Optimizely.Graph.Cms" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.UI.ContentManager" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Hosting" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.UI.VisitorGroups" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.Shell.UI" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.UI" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Events.ChangeNotification" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.AspNetCore.TagHelpers" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.AspNetCore.HtmlHelpers" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.Cms.TinyMce" Version="13.0.0-preview4" />

Step 4: Update startup configuration

CMS 13 requires explicit service registration instead of relying on the metapackage to wire everything up. Open Startup.cs and update the ConfigureServices method.

Before (Commerce 14 / CMS 12):

services
    .AddCmsAspNetIdentity<ApplicationUser>()
    .AddCommerce()
    .AddAdminUserRegistration()
    .AddEmbeddedLocalization<Startup>();

After (Commerce 15 / CMS 13):

services
    .AddCmsHost()
    .AddCmsCore()
    .AddCmsAspNetIdentity<ApplicationUser>()
    .AddCmsHtmlHelpers()
    .AddCmsTagHelpers()
    .AddCmsUI()
    .AddAdmin()
    .AddCmsImageSharpImageLibrary()
    .AddTinyMce()
    .AddContentGraph()
    .AddContentManager()
    .AddCommerce()
    .AddVisitorGroupsMvc()
    .AddVisitorGroupsUI()
    .AddAdminUserRegistration()
    .AddEmbeddedLocalization<Startup>();

services.Configure<DataAccessOptions>(options =>
{
    options.UpdateDatabaseCompatibilityLevel = true;
});

The UpdateDatabaseCompatibilityLevel setting ensures the database schema migrates correctly during the upgrade.

Step 5: Configure Content Graph

CMS 13 integrates Content Graph natively. Add the configuration to appsettings.json:

{
  "Optimizely": {
    "ContentGraph": {
      "GatewayAddress": "https://cg.optimizely.com",
      "AppKey": "<your-app-key>",
      "Secret": "<your-secret>",
      "SingleKey": "<your-single-key>",
      "AllowSendingLog": "true"
    }
  }
}

Replace the placeholder values with your actual Content Graph credentials from the Optimizely portal.

Step 6: Build and run the migration

Restore packages and build:

dotnet restore
dotnet build

Start the application, then navigate to the commerce migration endpoint:

https://localhost:5000/Optimizely/commerce/migrate

This updates the database schema and migrates data to the Commerce 15 format. The endpoint path has changed from /episerver/commerce/migrate to /Optimizely/commerce/migrate.

Step 7: Verify the upgrade

Once migration completes, verify the Commerce admin UI at:

https://localhost:5000/Optimizely/Commerce/

Check that:

• The Commerce admin interface loads without errors
• Catalog structure and products are intact
• Order history is accessible
• Scheduled jobs are visible

Source code considerations

Depending on the complexity of your Commerce solution, you may need additional source code changes due to API differences between CMS 12 and CMS 13. Common areas that require attention:

• Custom controllers — Verify your MVC controllers compile against the CMS 13 API surface
• Search and Navigation — If your commerce catalog search uses Search and Navigation, you must migrate to Graph
• Third-party add-ons — Commerce 15-compatible versions for add-ons will be released separately; check compatibility before upgrading
• Scheduled jobs — The API is unchanged, but verify any commerce-specific jobs work correctly
• Custom promotion/discount engines — Test pricing and promotion logic after migration

For CMS-specific breaking changes (Search and Navigation removal, Graph schema changes), see the CMS 13 upgrade guide.

📝 Check your understanding 3 questions

Related content

Continue your journey with these related pages.

📖Understand the concepts

• Optimizely Commerce
• Commerce Connect
• Content Delivery with Graph

🔧Follow a guide

• Upgrade to CMS 13
• Migrate from Commerce Connect
• Set Up Optimizely Graph