Large Cart performance tips

This page provides best practices for managing large Carts in Composable Commerce. The focus is on achieving functional goals while maintaining optimal performance. These recommendations help developers, solution architects, and product managers build scalable and responsive B2B and B2C commerce solutions.

What is a large Cart?

Defining what constitutes a large Cart goes beyond counting Line Items. While a high volume of distinct Line Items is a primary characteristic, other factors contribute to the size of a Cart, complexity, and the processing load it imposes on the system.

Large Carts can be characterized by one or more of the following:

• High volume of distinct Line Items: A Cart containing many different Products or Product Variants.
• Data volume per Line Item: Products referenced in Line Items possess extensive variant information, numerous custom attributes, or multiple localizations.
• Complexity of applied logic: Carts subjected to numerous or intricate discounts, complex shipping rules (for example, multiple destinations), or varied tax calculations for different items or regions.

Factors affecting Cart size and complexity

Several factors contribute to the size of a Cart object and the computational effort required to manage it:

• Line Items: Each Line Item represents a distinct Product Variant and directly contributes to the Cart's data volume and complexity.
• Custom Line Items: While Custom Line Items do not originate from the Product catalog, they do increase the size of the Cart and the amount of data that must be processed.
• Product data richness: The characteristics of the Products added to the Cart play a crucial role. If they have a high number of Product Variants and extensive attributes (especially localized ones), this data, even if not fully embedded in the Cart object by default, influences the information fetched or processed during Cart operations and recalculations.
• Custom Fields: Using Custom Fields on the Cart itself, and on individual Line Items and Custom Line Items, increases the size of the Cart. Each Custom Field and its value become part of the Cart's JSON representation. A gradual increase in the number of Custom Fields over time, driven by evolving business requirements, can lead to gradual data creep. While each addition may seem minor, their cumulative effect can significantly increase Cart size, pushing it toward performance thresholds without a single obvious cause. This relates to general JSON document size considerations.
• Applied promotions and discounts: Each Discount Code or direct Cart Discount added to the Cart increases the processing required to recalculate totals. When a large number of discounts (for example, over 100) are used, Cart calculations can slow down due to the need to load, parse, validate, and apply them.
• Shipping complexity: Configurations using multiple shipping addresses, multiple Shipping Methods, or the use of custom Shipping Methods all contribute to a larger Cart data structure and increase the processing required to determine costs and taxes.
• Tax information: Detailed tax information, especially when using External or ExternalAmount tax modes where tax rates or amounts are provided per line item or Shipping Method, adds to the Cart's data load.

API limits and performance recommendations

JSON document size

• Hard Limit: Any single JSON document persisted through the API, including Cart objects, must not exceed 16 megabytes. Attempting to save a Cart that would result in a document larger than this will lead to a ResourceSizeLimitExceeded error.
• Performance recommendation: For optimal performance, especially for documents that can grow large, such as a Cart with many line items or a Product with many variants, we strongly recommend keeping the document size to 2 MB or less. For average documents, a target of 100 KB or less is advisable. The 2 MB recommendation is especially relevant for large Carts, as all other factors like (Custom) Line Items and Custom Fields contribute to this total size.

Line Items

• Hard limit: While there is no hard limit for the number of line items in a Cart object, use the recommendation of a 2 MB maximum for large documents as guidance.
• Performance guideline: The actual number of line items that can be performantly handled will depend significantly on the data richness of each line item (for example, complexity of the Product Variant, number of Custom Fields). The primary concern is the resulting total Cart JSON size rather than an absolute line item count. In general, the simpler the Product definitions in your Project data, the more line items can be added without impacting performance. Carts that contain more than 500 line items should be regularly monitored for JSON size and API response times to ensure acceptable performance.

Update actions per request

• Hard limit: A single API request to update a resource (for example, a Cart update) can contain a maximum of 500 update actions. This is crucial for designing efficient bulk operations on Carts.

Reference expansion depth

• Hard limit: When using reference expansion in API GET requests, an expansion path is limited to a maximum depth of 3 references. This impacts the size of data retrieved if expansions are used when fetching Cart details.

Principles for optimizing performance

Achieving high performance with large Carts involves adhering to several core principles that span data modeling, API interaction patterns, and strategic architectural choices. These principles aim to keep Cart operations lean, fast, and scalable.

Minimize Cart document size

Keeping Cart documents lean reduces network transfer times, client-side processing overhead, and server-side load.

• Avoid including extensive or redundant information if it can be derived or fetched separately when needed for display (for example, detailed product specifications not essential for the Cart). Consider using GraphQL to fetch accurate Cart data.
• Only add Custom Fields to the Cart entity, Line Items, or Custom Line Items if they are strictly necessary for core Cart logic.
• Avoid storing large or verbose JSON blobs in a single Custom Field. Use a more structured and lightweight format when possible to keep queries efficient.

Efficient API request usage

How applications interact with the Carts API significantly influences performance.

• Always group multiple changes to a Cart into a single API request. The API supports up to 500 update actions in one call. This reduces network latency compared to sending many individual requests and allows for more atomic operations. For example, adding 10 items should be a single request with 10 addLineItem actions, not 10 separate requests.
• Design client-server interactions to avoid many small API calls to update or fetch the Cart in quick succession. For example, if a user can make several modifications in the UI before confirming, accumulate these changes and send them as a single batched update.

Data modeling strategies

Decisions made during Product and pricing data modeling have a significant and often underestimated impact on Cart performance.

• Product data: Create more Products with fewer Product Variants. Simple Product structures mean less complex data to reference or process when adding a Line Item to a Cart or when recalculating the Cart.
• Pricing and discounts: Complex pricing models, with many distinct price entries per Product Variant or intricate discount rules, increase the computational load during Cart recalculations. Every item added, quantity change, or coupon application can trigger these potentially expensive operations.
• Stores: Use Stores for data partitioning. By associating a Cart with a specific Store (using the store field in the CartDraft), you scope the Product data considered during Cart operations. Only the prices, localized attributes, and other data defined for that Store are loaded and evaluated. For Products with extensive data across many countries, Channels, or Customer Groups, this filtering reduces the amount of data processed for each Line Item and significantly improves performance for large Carts.

Common scenarios and performance insights

Large Carts can impact system performance in different ways, depending on their structure and usage patterns. Understanding these scenarios and applying targeted optimizations is key to maintaining responsiveness. The following section outlines typical large Cart scenarios, tested through various load test variants. It highlights their potential impact, contributing factors, and recommended mitigation strategies, backed by internal performance metrics.

Scenario 1: Product data size

Even a Cart with a moderate number of Line Items can become problematic if each item references a Product with a complex structure (for example, hundreds of attributes or excessive variants). This scenario shows how the size and complexity of the underlying Product data affect the performance of creating a large Cart. This test measures the impact of Product modeling choices on a foundational Cart operation.

• Action: Create a new Cart with 500 Line Items in a single POST /carts request.
• Load profile: A sustained load of 5 requests per second for 5 minutes.

The test includes 5 runs, each with a different average Product size. The variation is achieved by adding a different number of attributes or populating Custom Fields with varying amounts of text.

Maintaining a small Product data footprint improves performance. The experiment demonstrates a direct correlation between the size of Product data referenced by Line Items and the performance of Cart creation. For the same operation, the API is nearly four times faster when using small (5 kB) Products compared to large (200 kB) Products.

Scenario 2: Large amount of items

This scenario is common in B2B transactions or large retail orders. This scenario measures how API performance behaves when the number of Line Items in a Cart increases. It helps customers understand the practical limits of Cart size and when performance might become an issue.

• Action: Create a new Cart with N Line Items in a single POST /carts request.
• Load profile: A sustained load of 5 requests per second for 5 minutes.
• Data: Products used in the test are the same in each run.

The test runs in five iterations, each with a different number of Line Items.

The system reliably processes large Carts, but response times increase with the total number of items. Performance for large transactions can be improved by reducing the data payload per Product or using data-filtering mechanisms like the Stores feature.

Scenario 3: Batch update actions

This scenario shows the performance benefits of batching multiple update actions into a single API request rather than sending them individually.

• Load profile: Measure the total time to complete one full transaction—creating a Cart with 500 Line Items. This transaction is triggered multiple times over 5 minutes to get stable metrics.

• A single, large request has a slightly higher response time than a small one. However, the total time to complete the entire business operation is much lower. The average response time for a single request with 500 update actions is about twice as slow as a request with 10 update actions. Still, it is about 20 times faster in total duration to process all 500 line items in one request versus 50 smaller requests.

• Sending a single request with all updates minimizes networking and processing overhead, resulting in much lower total processing time. When updating many Cart items at once, group as many update actions as possible into a single API call for the best performance.

• This analysis provides a clear and proven approach for enhancing application performance. By consolidating frequent API calls into larger, more meaningful requests, you can build more responsive, robust, and scalable systems that deliver a better user experience.