Upgrade Guide: Commerce 14 to Commerce 15 preview

Tue, 31 Mar 2026 03:59:41 GMT

This document provides step-by-step instructions to upgrade a Commerce site from Commerce 14/CMS 12 to Commerce 15/CMS 13 preview.

Overview

This upgrade includes:

Commerce: 14.15.3 → 15.0.0-preview1

CMS: 12.31.2 → 13.0.0-preview4

.NET: 8.0 → 10.0

Prerequisites

Visual Studio 2022 with .NET 10.0 SDK

SQL Server (LocalDB or full instance)

Basic understanding of Optimizely Commerce and CMS

Step 1: Create a new Commerce 14 empty site from template

To create a baseline Commerce 14 site from template:

Run the template command:

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

Open the project, restore packages, and build it

Press F5 and create a user by accessing: https://localhost:5000/util/register

Migrate Commerce data: https://localhost:5000/episerver/commerce/migrate

Verify the CMS/Commerce Admin UI: https://localhost:5000/episerver/cms

Verification: Ensure the site is running without errors before proceeding.

Step 2: Update Project Configuration

File Modified: [CoCo14.csproj]

Target Framework

<TargetFramework>net10.0</TargetFramework>  <!-- was net8.0 -->

Package References

Before (Simple metapackage approach):

<PackageReference Include="EPiServer.CMS" Version="12.31.2" /> 
<PackageReference Include="EPiServer.Commerce" Version="14.15.3" />

After (Explicit package references):

Commerce packages:

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

CMS packages (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 3: Update Startup Configuration

File Modified: [Startup.cs]

Update Service Registration

Before (Commerce 14 - Simple metapackage registration):

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

After (Commerce 15 - Explicit service registration):

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; 
});

Step 4: Update Application Settings

File Modified: [appsettings.json]

Add the following Optimizely configuration section for Content Graph

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

Important: Replace the placeholder values (<app-key>, <secret>, <single-key>, <instance-id>) with your actual credentials from the Optimizely portal.

Step 5: Restore, Build, and Run Migration

After making all the changes:

Restore packages:

dotnet restore

Build the project:

dotnet build

Run the application:

- Press F5 in Visual Studio, or

- Run dotnet run from the command line

Run Commerce migration:

- Navigate to: https://localhost:5000/Optimizely/commerce/migrate

- This will update the database schema and migrate data to Commerce 15 format

Step 6: Verify the Upgrade

Access the Commerce Admin UI: Navigate to https://localhost:5000/Optimizely/Commerce/

Important Notes

Code Compatibility

Depending on your Commerce solution, you may need to update source code due to API changes in CMS 13 and Commerce 15. See the CMS 13 Pre-Release overview for details.

Commerce 15-compatible versions for popular Commerce add-ons will be released later

Preview Versions

Commerce 15.0.0-preview1 and CMS 13.0.0-preview4 are pre-release versions

Not recommended for production use

Use for evaluation and testing purposes only

Additional Resources

How to create an empty commerce project from which you can build your Optimizely Commerce Connect website

Official upgrade guide: CMS 12 to CMS 13

Overview of Commerce 15 pre-release

Blog posts by Viet Anh Nguyen

Upgrade Guide: Commerce 14 to Commerce 15 preview