Cart v2 overview

Optimizely did not want to continue using IHandler because native async support was impossible and performance profiling was difficult due to its use of call chaining. Every step counted the combined processing time of every following step, increasing the effort required to identify the origin of performance problems.

IPipeline did not have the chaining problem of IHandler, but it was incompatible with async code. Introduction of the intermediate workspace type is useful for the future but is not currently used.

The constraints around async are in place due to embedded dependencies on legacy code. Optimizely has observed that in .NET framework builds of Configured Commerce, attempting to use native async code (the C# async/await keywords) can cause legacy objects like IUnitOfWork to be lost in legacy code called later in the same overall request.

The cart touches nearly all functionality of Configured Commerce. Enabling native async requires a rewrite of the code, which Optimizely does not currently have the time to do. As a consequence, all base async code still forces it to run synchronously by attaching .GetAwaiter().GetResult() to the async method and returning Task.CompletedTask instead of using a native async function.

The changes to improve cart performance necessitated a new internal API version, called v2. Since this introduces a large break, it allowed configuration for async in the future. The improved performance profiling capability also increased productivity during v2 development.

Future legacy-free code built around IAsyncPipeline can fully support native async.

The Admin Console now has a setting called Cart Version with a v2 option. Only those with ISC\_System can access it, so you must work with Optimizely Support to enable it.

When using this setting, the .NET code routes to the IAsyncPipeline version of the cart instead of the legacy IHandler version, but the final objects returned to the HTTP caller are the same as before, avoiding the need to rework Spire customizations.

The new code is within the namespace Insite.Cart.Services.Async. Optimizely intentionally re-used the same internal names to make migration a straightforward process. If you customized the legacy GetCartHandler, GetCart in the new namespace is the new location. Continuing that example, if you customized the CopyCustomPropertiesToResult step within GetCartHandler, the step within the new GetCart is the same place in the sequence with almost the same name: it is CopyCustomPropertiesToResultAsync as .NET convention is that methods returning a Task should be postfixed with Async, even though async is not yet ready due to mixed legacy code.

The REST API is unchanged. If the .NET customizations your Spire customizations relied upon are converted, you do not need to make any Spire changes.

The primary method used to improve performance was to eliminate query loops–scenarios where a query was called multiple times in a loop with a single parameter. One example of this is the single item AddCartLine is gone in favor of a bulk-optimized AddCartLines. This works well with a single item but should significantly outperform v1, where v1 AddCartLines called AddCartLine in a loop.

As part of optimization, Optimizely discovered opportunities to improve Cart v1 performance in a backward-compatible way. As a result, Configured Commerce releases throughout 2025 had improvements to Cart v1 without any customer or partner effort. Before committing to a v2 conversion, you should re-test cart performance with 5.2.2508 or newer to see if the v1 improvements are enough.

With the release of v2, Optimizely is averse to breaking changes and would only do so with encouragement from partners. Currently, the primary performance constraint is the large entity objects pulled from the database. For example, retrieving a Product entity involves accessing more than 100 columns for every record regardless of what is actually needed by the storefront. Entity framework performance degrades as the column count increases, and these large objects create major overhead. Using specialized types with fewer columns would proportionally improve performance but make those objects less flexible for creative usage by our partners.

Another challenge is that the GetCart process is not a read-only action: it spends time fixing the cart before returning it to the user. Any changes here could destabilize cart functionality that expected the cart to be cleaned up on-demand instead of at the time an action was done that affects it.

Even though resolution of the biggest performance impediments for v2 may be out of reach for compatibility reasons, Optimizely may have opportunities for smaller wins.