Cart v2 overview

Optimizely did not want to continue using IHandler because Optimizely couod not implement native async support, and Optimizely found performance profiling 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. Optimizely introduced the intermediate workspace type for future use, but it is not currently used.

Embedded dependencies on legacy code impose constraints around async. 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 code to lose objects like IUnitOfWork 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, which Optimizely calls v2. Because this introduces a large break, it allows configuration for async in the future.

Future legacy-free code that uses IAsyncPipeline can fully support native async.

The Admin Console now has a setting, 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 system returns the same final objects to the HTTP caller 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 or GetCart in the new namespace, it 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 you should postfix methods returning a Task with Async, even though async is not yet ready due to mixed legacy code.

TThe REST API remains unchanged. If you convert the .NET customizations your Spire customizations relied upon, you do not need to make any Spire changes.

Optimizely primarily improved performance by eliminating query loops–scenarios where the system called a query multiple times in a loop with a single parameter. One example of this is that Optimizely replaced the single item AddCartLine with 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, Optimizely improved Cart v1 in Configured Commerce releases throughout 2025 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 retrieved from the database. For example, retrieving a Product entity involves accessing more than 100 columns for every record regardless of what the storefront actually needs. 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 Optimizely 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 system to clean up the cart on-demand instead of at the time an action occurred that affects it.

Even though Optimizely may not be able to resolve the biggest performance impediments for v2 for compatibility reasons, Optimizely may have opportunities for smaller wins.