Commerce 15 Is Five Upgrades Sharing a Version Number
.NET 8 reached end of support on November 10. If you run Optimizely Commerce 14, you've had the "when do we go to 15" conversation, and someone in the room has probably said "it's mostly a package bump." It isn't.
There's good strategic writing on why to make this move. Scott Reed's Opticon recap makes the connectivity case, and Graham Carr's "isn't an upgrade, it's a reset" rightly argues for scoping it as a programme. This post is the layer below that: the execution plan we used for a headless B2B commerce platform with entitlement-scoped catalog visibility, where a wrong search result isn't a relevance bug. It's a data leak.
The thesis: Commerce 15 is five upgrades that share a version number, and only two of them have to ship together. Everything else should be in production on CMS 12 before you cut the branch.
Five upgrades, one version number
Commerce 15 requires CMS 13, and you upgrade both at the same time. Unpack that and you get:
- .NET 8 → .NET 10. Required by both CMS 13 and Commerce 15.
- Newtonsoft.Json → System.Text.Json. Commerce 15 no longer brings Newtonsoft in transitively, and custom converters get rewritten.
- CMS 12 → 13. Opti ID and Optimizely Graph are mandatory.
SiteDefinitionbecomes the Application model. Search & Navigation is gone. - Commerce 14 → 15. The legacy workflow engine is replaced by processor-based APIs (
IPurchaseOrderProcessor,IPaymentProcessor,IShipmentProcessor). Credit card storage is removed. Catalog search moves to the Graph provider inOptimizely.Graph.Commerce, and Visual Builder becomes the default catalog editor. - The Graph schema and SDK port. CMS 13 replaces the flat, per-type schema with a unified inheritance schema, and a CMS 12 site and a CMS 13 site can't share a Graph instance.
The CMS 13/Commerce 15 core and the schema cut are coupled. They land on cutover day. The .NET lift, most of the serialization work and most of the search work aren't. Teams that treat all five as one "bump the packages" project discover the dependency chain mid-sprint.
Shrink the cutover: pull work onto CMS 12
CMS 12 officially supports .NET 10, and Commerce 14 joined it at 14.46.0. That means your current main branch can absorb a lot of the program:
- Retarget to
net10.0and move to EF Core 10. DXP selects the runtime image from your package's target framework, per environment, so Integration can go first. [VERIFY against your own pipeline before you count on it.] - Move your own serialization to System.Text.Json. One caveat: CMS 12 and Commerce 14 still use Newtonsoft internally, so converters that plug into platform serialization wait for cutover. Your API layer, integration clients and caching move now.
- Burn down the obsoletes. Commerce 14's deprecation warnings are a map of what Commerce 15 removes. Fail the build on them, and replace
ServiceLocatorcalls with constructor injection while you're there. [VERIFY ServiceLocator status in CMS 13.]
Find → Graph first? Optimizely says wait.
Start with the official position, because it's the opposite of what we did. Optimizely's certification guide says that if you're on CMS 12 and considering Graph, you should wait for CMS 13: the schema changes, and you'll migrate twice. The Alloy migration guide also upgrades CMS first and replaces Search & Navigation second, to isolate failures.
That's the right default. Writing the query layer and the frontend GraphQL against the CMS 12 schema, then porting both again, costs real money.
We went the other way anyway, for three reasons:
- The risk lives in the search semantics, not the syntax. Translating Find filters into Graph filters is where an entitlement predicate gets subtly widened. We wanted that translation proven in production, on a platform we already trusted, before anything else changed.
- It separates two failure modes. If a visibility bug shows up after cutover, you want one suspect (the platform), not two.
- A seam made the second port cheap. All Graph querying lived behind one query-builder layer, so the CMS 13 port touched that layer and not the call sites.
If search is a box in your header, follow Optimizely's order. If search is effectively your authorization surface, consider my order or operations.
Branch strategy and the one-way door
Main stays on CMS 12 and shippable. All CMS 13/Commerce 15 work lives on one long-lived integration branch that takes forward merges from main on a fixed cadence. Phase-one work lands on main and flows forward; it never starts on the integration branch.
flowchart LR subgraph main["main: CMS 12 / Commerce 14, always shippable"] A["net10 TFM + EF Core 10"] --> B["System.Text.Json in app code"] B --> C["Obsolete API + ServiceLocator cleanup"] C --> D["Find → Graph behind query seam"] end subgraph int["integration: CMS 13 / Commerce 15"] E["Package bump + compile fixes"] --> F["Port query seam to Graph.Cms.Query"] F --> G["Conventions → computed fields"] end D -->|"cut branch"| E main -.->|"forward merges"| int FE["Frontend: .graphql docs → unified schema"] --> H G --> H["Parity gates, side-by-side environments"] H --> R["Cutover rehearsals from restored backups"] R --> X["Cutover"]Two constraints shape the end of the plan:
- The database migration is one-way. Rollback means restoring a backup. Rehearse the cutover against a restored production backup, with timings, more than once.
- Graph needs its own instance. DXP can provision a separate Graph instance for the CMS 13 slot while CMS 12 keeps the existing one. That's what makes side-by-side validation possible.
Seams contain the port
The query-builder seam paid off exactly as hoped. The port went from the CMS 12-era Graph client (Optimizely.Graph.Client and its TypeQueryBuilder) to the CMS 13 Optimizely.Graph.Cms.Query SDK, and nothing outside the seam noticed.
// The seam: call sites ask for entitled products and never see the query SDK.
public interface ICatalogSearch
{
Task<CatalogResults> SearchAsync(CatalogQuery query, BuyerContext buyer, CancellationToken ct);
}
// CMS 13 implementation. Illustrative; check names against the SDK version you pin. [VERIFY]
public sealed class GraphCatalogSearch(IGraphContentClient graph, IEntitlementFilter entitlements)
: ICatalogSearch
{
public async Task<CatalogResults> SearchAsync(CatalogQuery query, BuyerContext buyer, CancellationToken ct)
{
var q = graph.QueryContent<ProductContent>()
.SearchFor(query.Text)
.Where(p => p.MarketId == buyer.MarketId);
// App-layer authorization: same predicates as CMS 12, translated once, tested in pairs.
q = entitlements.Apply(q, buyer);
return CatalogResults.From(await q.Skip(query.Offset).Limit(query.PageSize)
.IncludeTotal().GetAsContentAsync(ct));
}
}
Note the entitlement filter. Graph's restricted-content model is role-based and evaluated at index time. It doesn't know your business entitlements, and there's no per-user impersonation. Authorization stays in your code and carries over unchanged.
Conventions migrate too. If you extended the CMS 12 Graph model with IContentApiModelProperty, those become computed fields: extension methods registered through AddContentGraph(configureConventions: ...).
public static class ProductIndexFields
{
// Computed at index time. Return primitives (or arrays of them), never CMS data.
public static string[] VisibilityKeys(this ProductContent product)
=> product.VisibilityRules?.Select(r => r.Key).ToArray() ?? [];
}
services.AddContentGraph(configureConventions: conventions =>
{
conventions.ForInstancesOf<ProductContent>()
.IncludeField(p => p.VisibilityKeys(), IndexingType.Queryable);
});
Constraints worth knowing up front:
- Conventions require CMS 13.1.0. Computed fields on content contracts, and querying them through the SDK, need 13.1.1.
- Computed fields can't return CMS data: no
ContentReference,ContentArea,Blob,LinkItem, orPageData/BlockData. IndexingTypeis optional in the API. Set it explicitly anyway. Graph validates indexing types across the whole contract hierarchy at startup, and implicit defaults are how mismatches sneak in.
The frontend is its own workstream. Every headless GraphQL document gets rewritten for the unified schema: metadata moves under _metadata, URLs become structured objects, ContentLink.Expanded is gone, and rich text comes back structured [VERIFY]. Dozens of .graphql documents is normal for a mid-size storefront. Staff it in parallel rather than discovering it in QA.
Proving parity when a leak is the failure mode
For an entitlement-scoped catalog, "search works" means two things: buyers see everything they're entitled to, and nothing they aren't. The second one is what ends up in an incident report.
Run both stacks against the same data. Every environment shares the same upstream data sources, so the CMS 12 reference environment and the CMS 13 environment serve the same catalog side by side. Testers validate CMS 13 directly against live CMS 12: same buyer, same query, two answers.
The gate is the visibility suite. The primary control is a QA visibility regression suite organized by buyer class, market scope and catalog visibility rules, with zero-tolerance leakage gates. A relevance difference is a ticket. One item visible to a buyer who shouldn't see it fails the QA suite.
Cover what nobody enumerated. Hand-written scenarios only cover the cases someone thought of. For the rest, we used predicate-to-scenario traceability: every filter predicate translated from the old query layer gets a paired positive and negative scenario, one buyer who should match it and one who shouldn't. A predicate without a pair means the suite isn't done. Add a security review of the filter-builder code, because that's where a dropped clause silently widens visibility.
Don't make "same as CMS 12" the bar. We considered automatically diffing results between the two stacks and passed. A diff proves the new stack matches the old one, including any leak the old one may have already had. The scenario suite asserts what should be visible, so it tests correctness rather than consistency. It also skips the hard parts of diffing: replaying buyer identities across both stacks, normalizing two different result schemas, and absorbing sync-timing noise. The tradeoff is real. We accepted thinner coverage of long-tail query shapes in exchange for explicit, reviewable assertions on the predicates that matter.
Two operational rules:
- Keep the CMS 12 environment deployed and fed until every gate passes. It's your reference and your fallback.
- Compare during quiesced windows. Imports and sync jobs land at different moments in each stack, and timing noise will burn days of triage if you compare mid-feed.
Go/no-go and sizing
Phase-0 decisions:
- Add-ons. Geta NotFoundHandler, Geta Sitemaps and Stott RobotsHandler were all incompatible at CMS 13 GA, and all three have shipped CMS 13 versions since. NotFoundHandler 7.x needs CMS 13.1 or later. Optimizely's own compatibility table still listed two of them as "remove; await update" at last check. Trust the package feeds, not the table.
- Content Delivery API. CDA 13.0.0 shipped in August, so the decision is now migrate-to-Graph versus CDA 13. CDA 13 drops the Content Definitions and Content Management APIs; management moves to the built-in CMS REST API.
- Satellite packages. Inventory every connector you depend on and confirm a CMS 13/Commerce 15 build exists before you commit dates. [VERIFY your list.]
Size it by grepping before you estimate. Search the repo for the breaking surfaces and count call sites. An illustrative example for a mid-size headless B2B codebase:
| Breaking surface | What changes | Illustrative hits |
|---|---|---|
Newtonsoft.Json |
Converters move to System.Text.Json | ~50 |
ServiceLocator |
Constructor injection | ~80 |
SiteDefinition |
Application model | ~30 |
OpenIddict |
CMS 13 REST API auth setup [VERIFY] | ~15 |
ICatalogSystem |
Content API, removed methods | a handful |
| Legacy workflow, card storage | Processor APIs, tokenization | 0 |
Zero is a finding too: it takes the biggest Commerce 15 risk off the board. For a tooled version of this, Adnan Zameer's cms13-scan is a deterministic readiness scanner built for exactly this job.
On duration: the mechanical port is the part that compresses. Scanners, scripted refactors and AI-assisted migration make short work of package bumps, namespace moves and converter rewrites. What doesn't compress is proving the new stack behaves correctly, and on a headless B2B codebase with entitlement-scoped search, that's most of the calendar. Plan in months, not weeks, and size the parity work separately from the port. [REVIEW]
Lessons
- Decompose before you estimate. A single "Commerce 15" line item hides five projects with different risk profiles.
- The cutover is a size you choose. Anything that runs on CMS 12 should ship on CMS 12.
- Seams are cheap insurance. One query-builder layer turned a platform-wide port into a contained one.
- Matching the old system isn't the same as being correct. Assert what should be visible; don't just compare.
- Compatibility tables lag. Check the feeds, and check again before go/no-go.