Shopping Carts are a vital element in any digital commerce platform. They act as a temporary container for items a customer intends to purchase and are central to the entire checkout process. Efficiently managing Carts is essential for providing a seamless and reliable shopping experience.
The Cart data model
In Composable Commerce, the Cart entity is a rich object that holds all the necessary information for a shopping Cart session and the subsequent checkout.
| Component | Why it matters |
|---|---|
| User context | A Cart is typically tied to a customerId or anonymousId, which lets you retrieve the correct Cart and migrate guest activity after sign-in. For B2B scenarios, a businessUnit can also be used for association. |
| Commercial state | Fields such as currency and country determine the correct prices for the Line Items. Other fields related to taxes, Cart Discounts, Discount Codes and shipping determine the Cart totals that drive checkout decisions. |
| Purchasable content | What the customer wishes to buy is captured via lineItems, which are snapshots of specific Product Variants, and customLineItems, which represent items that don't exist in the product catalog (for example, personalization fees or special charges). |
| Business-specific data | The Cart is extendable with customFields that store additional data, such as a flag for a "gift Cart" or an internal order type. Note that using many Custom Fields increases the Cart's size and may impact performance for large Carts. |
| Cleanup Policy | The deleteDaysAfterLastModification field (default: 90 days) automatically deletes inactive Active Carts to maintain system performance and manage database size. |
| For the full Cart representation, including operational fields such as cleanup policies and every available sub-object, see the Cart API reference. |
Cart lifecycle: the cartState field
A Cart progresses through several states. The
cartState field indicates its current status:Active: the default working state for a Cart that can still be updated.Frozen: a checkout control state that prevents Cart modifications that would affect the total price.Merged: a guest Cart whose contents were transferred during sign-in or sign-up. Cannot be modified anymore.Ordered: a completed Cart that has already been converted into an Order. Cannot be modified anymore.
For the full lifecycle semantics, including freeze behavior and merge behavior, see the Carts and Orders overview.
Key architectural decision: choose the right Cart scope
A critical decision when implementing Carts is whether to use Store-scoped or Project-scoped Carts. This choice is primarily driven by your business's multi-store strategy.
- Store-scoped Carts: these Carts are explicitly linked to a specific Store. This automatically constrains the Cart's context, including available products (via Product Selections), prices, currencies, and languages. This has the benefit of making the Cart size smaller.
- Project-scoped Carts: these Carts are not tied to any specific Store. They offer more flexibility but require the application to manage the context (like currency, country, and product availability) more explicitly.
Performance benefits of Store-scoped Carts
Store-scoped Carts offer significant performance advantages for large Carts by partitioning Product data at the infrastructure level. When a Cart is scoped to a Store, only the prices, localized attributes, and product data relevant to that Store are loaded and evaluated. For B2B scenarios with extensive product catalogs or complex pricing structures, this data filtering can dramatically improve Cart operation performance. Learn more in the Large Cart performance tips guide.
Let's break down common scenarios to help you decide.
Scenario 1: Customers are exclusively associated with a single Store
- Description: each customer account is tied to one specific Store. For example, a Project has two distinct brands, 'Electronics High Tech' and 'Zenith Living', each represented by a Store. A customer is registered only with 'Electronics High Tech' and shops exclusively within that brand's context.
- Recommendation: Store-scoped Carts.
- Reasoning:
- Contextual integrity: the Cart automatically inherits the correct product assortment, subset of pricing, and availability from the customer's designated Store.
- Simplicity: This model aligns directly with the "one customer, one store" paradigm, reducing the need for complex application logic to determine the correct context.
Scenario 2: Customers can access all stores (global experience)
- Description: customers can browse and shop from any Store, or if the Project is simple and doesn't use the Store model for segmentation. The goal is a single, unified Cart experience across all contexts.
- Recommendation: Project-scoped Carts.
- Reasoning:
- Unified experience: a Project-scoped Cart provides a persistent experience even if the customer switches their viewing context (for example, changes country or language that might map to different Stores).
- Flexibility: the Cart isn't locked to one Store's rules. However, your application is still responsible for applying the correct context (for example, country, currency, shipping destination) at checkout to calculate the final price and taxes.
Scenario 3: A unified Cart across a subset of Stores
- Description: a customer is associated with a specific group of Stores (for example, 'Store USA' and 'Store Canada') and expects a unified Cart between them, but not with other Stores (for example, 'Store Iceland'). They add an item in the 'USA' context and expect to see it when they switch to the 'Canada' context.
- Recommendation: Project-scoped Carts.
- Reasoning:
- Cross-Store persistence: a Store-scoped Cart is locked to its originating Store. To allow a single Cart to persist and be modified across different Store contexts (USA and Canada), a Project-scoped Cart is necessary.
- Application-managed logic: your application takes on the critical responsibility of managing the context. It must:
- Enforce product eligibility: check that a product can be added to the Cart based on the Product Selections of the currently active Store.
- Apply contextual rules: resolve prices, taxes, and inventory based on the active Store or other rules (for example, shipping destination).
- Manage Store group boundaries: implement logic to prevent items or context from excluded Stores (like 'Store Iceland') from being mixed into the Cart.
Scenario 4: Separate, distinct Carts for each Store
- Description: a customer associated with 'Store USA' and 'Store Canada' should have a separate Cart for each. When they are in the 'USA' context, they see their 'USA Cart'. When they switch to the 'Canada' context, they see their 'Canada Cart'.
- Recommendation: Store-scoped Carts.
- Reasoning:
- Contextual isolation: this is the standard behavior of Store-scoped Carts. The Cart for Store USA only contains items and follows rules relevant to Store USA.
- Application logic: your application must manage which Store context the customer is currently in and ensure it queries for the appropriate Store-scoped Cart.
Guiding principle
Use Store-scoped Carts when you want to enforce strict contextual boundaries (for example, products or prices) at the API level. Use Project-scoped Carts when you need the flexibility to create a shared or global Cart experience, but be prepared to manage the contextual logic within your application.