Grasp the core architectural concepts of the Carts API, from data models to key API actions, to inform your implementation strategy.
After completing this page, you should be able to:
- Explain the Cart data model, including its key components, user context, and lifecycle states.
- Analyze business requirements to determine whether to implement a Store-scoped or Project-scoped Cart.
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 | Description |
|---|---|
| Association | A Cart must be associated with a user context. This is done via customerId for registered customers or anonymousId for guest users. This link is crucial for retrieving the correct Cart and for merging a guest Cart into a customer's Cart upon sign-in. For B2B scenarios, a businessUnit can also be used for association. |
| Line Items | Carts contain lineItems, which are snapshots of specific Product Variants the customer wishes to buy. They can also contain customLineItems for items that don't exist in the product catalog (for example, personalization fees or special charges). |
| Pricing & Currency | Carts require a currency and a country to determine the correct prices for the Line Items. Price selection is a core function of the Composable Commerce platform. |
| Taxes | Carts must have valid tax information. This can be managed using Composable Commerce's built-in Tax Categories or by integrating with an external tax calculation service. |
| Shipping & Billing | The Cart holds shipping and billing addresses, as well as selected Shipping Methods. Shipping can be defined at the Cart level or for individual Line Items (item-level shipping). |
| Discounts | Discounts can be applied to the Cart automatically via Cart Discounts or manually via Discount Codes. |
| Custom Fields | You can extend the Cart object with customFields to store additional business-specific data (for example, a flag for a "gift Cart" or an internal order type). |
| Cleanup Policy | The deleteDaysAfterLastModification field (default: 90 days) automatically deletes inactive Active Carts to maintain system performance and manage database size. |
Cart lifecycle: the cartState field
A Cart progresses through several states. The
cartState field indicates its current status:Active: the default state for a new Cart. In this state, the Cart can be fully modified (items added, removed, or updated). AnActiveCart is the starting point for an order.Frozen: a special state where the Cart cannot be modified in any way that would affect the total price. This is typically used during the final stages of checkout, just before payment, to "lock" the price and prevent unexpected changes while the customer is completing payment.Merged: the state of a guest Cart after its contents have been successfully merged into a customer's Cart upon sign-in. AMergedCart can no longer be modified.Ordered: the final state after a Cart has been successfully converted into an Order. AnOrderedCart can no longer be modified.
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.
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 native 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.