Learning PathModule

Find and manage existing Carts

Discover efficient methods for retrieving and managing customer Carts.

Ask about this Page

Copy for LLM

View as Markdown

After completing this page, you should be able to:

Construct an optimized API query to retrieve a customer's Cart, selecting the correct endpoint and parameters for the given context.
Implement SDK logic to find and manage existing Carts for both anonymous and registered customers.

Before creating a new Cart, it is a crucial best practice to check if the customer (anonymous or logged-in) already has an active one. This prevents duplicate Carts, reduces data clutter, and allows customers to seamlessly resume their shopping session. Most commerce sites enforce a "one active Cart per customer" rule to simplify the user experience.

Construct the optimal query

To find the correct Cart efficiently, build a precise and performant query. For the full predicate syntax and field catalog, see Query predicates on Carts.

Step 1: Choose the right endpoint

Endpoint	When to use
Project-scoped: `/carts`	Use this when your application does not use Stores, or when you need to search across Store contexts, without knowing the exact Store the customer's Cart belongs to. You can optionally filter by store using a `where` predicate.
Store-scoped: `/in-store/key={storeKey}/carts`	Use this when the Store context is already known. This avoids an extra Store predicate and matches Store-restricted API Clients well.

Recommendation: when in doubt, start with the Project-scoped /carts endpoint. It provides the most flexibility.

Step 2: Build the where predicate

The where predicate is the most critical part of your query. For best performance, order the clauses from most to least selective.

Predicate component	Why it matters
`customerId="<id>"` or `anonymousId="<id>"`	Identifies the owner of the Cart. This is the primary and most selective filter.
`cartState in ("Active", "Frozen")`	Restricts the result to Carts that are still relevant to the shopping session. It excludes no longer modifiable Carts (`Ordered`, `Merged`).
`store(key="<store-key>")`	Adds Store isolation only when you query the `/carts` endpoint in a multi-Store setup.

The following is an example where predicate:

where=customerId="c123-..." AND cartState in ("Active", "Frozen") AND store(key="zen-electron-us")

Step 3: Add performance and consistency parameters

Use only the query parameters that support your retrieval rule and improve performance.

Parameter	Recommended value	Purpose
`sort`	`lastModifiedAt desc`	Makes the selection deterministic when more than one active Cart exists. By combining it with `limit=1`, you are guaranteed to retrieve the most recently updated customer Cart.
`limit`	`1`	Enforces the common "one active Cart per customer" rule and stops the query after finding the first match, improving thus performance.
`withTotal`	`false`	Skips unnecessary total-count calculation when you only need the top result. This can significantly speed up the API response and improve performance.

Working with large or complex Carts?

The query optimization strategies above work well for typical Cart operations. However, if you're building B2B solutions or handling Carts with hundreds of Line Items, extensive Custom Fields, or complex discount rules, consult the Large Cart performance tips guide for advanced data modeling and API usage strategies.

Complete API request example

Scenario: find the most recently modified active or frozen Cart for a logged-in customer in the zen-electron-us Store:

GET /carts?limit=1&withTotal=false&sort=lastModifiedAt desc&where=customerId="c123-..." AND cartState in ("Active", "Frozen") AND store(key="zen-electron-us")

Handling the response:

If a Cart is found: the API will return a results array with one Cart object. Your application should use this Cart.
If no Cart is found: the API will return an empty results array. Your application should proceed to create a new Cart when the user adds their first item.

Implementation with the SDK

Here is how you can implement this optimal query strategy using the TypeScript SDK.

For an anonymous user:

import { apiRoot } from "../../client";
import { Cart } from "@commercetools/platform-sdk";

async function getActiveAnonymousCart(
  storeKey: string,
  anonymousId: string
): Promise<Cart | undefined> {
  try {
    const { body } = await apiRoot
      .inStoreKeyWithStoreKeyValue({ storeKey })
      .carts()
      .get({
        queryArgs: {
          limit: 1,
          withTotal: false,
          sort: "lastModifiedAt desc",
          where: [`anonymousId="${anonymousId}"`, `cartState="Active"`],
        },
      })
      .execute();

    return body.results[0]; // Returns the cart or undefined if not found
  } catch (error) {
    console.error("Error fetching anonymous cart:", error);
    throw error; // Rethrow or handle appropriately
  }
}

For a logged-in customer:

import { apiRoot } from "../../client";
import { Cart } from "@commercetools/platform-sdk";

async function getActiveCustomerCart(
  storeKey: string,
  customerId: string
): Promise<Cart | undefined> {
  try {
    const { body } = await apiRoot
      .inStoreKeyWithStoreKeyValue({ storeKey })
      .carts()
      .get({
        queryArgs: {
          limit: 1,
          withTotal: false,
          sort: "lastModifiedAt desc",
          where: [`customerId="${customerId}"`, `cartState="Active"`],
        },
      })
      .execute();

    return body.results[0]; // Returns the cart or undefined if not found
  } catch (error) {
    console.error("Error fetching customer cart:", error);
    throw error; // Rethrow or handle appropriately
  }
}

How to enforce a single active Cart

The primary way to enforce this is through your application logic. By always performing the optimal query described above (limit=1) before creating a new Cart, you ensure that you always reuse an existing active Cart if one is found.

How to handle multiple Carts

While a single active Cart is the most common pattern, some business models might require multiple active Carts per user (for example, a B2B "projects" Cart and a "personal" Cart).

If your business logic allows multiple active Carts, modify your query strategy:

Remove limit=1: allow the query to return all active Carts.
Use sort: ensure results are consistently ordered (for example, lastModifiedAt desc).
Implement selection logic: your application must provide a way for the user to view and select which Cart they want to interact with.

Example of getting all active Carts for a customertypescript

async function getAllActiveCustomerCarts(
  storeKey: string,
  customerId: string
): Promise<Cart[]> {
  try {
    const { body } = await apiRoot
      .inStoreKeyWithStoreKeyValue({ storeKey })
      .carts()
      .get({
        queryArgs: {
          sort: "lastModifiedAt desc",
          where: [`customerId="${customerId}"`, `cartState="Active"`],
        },
      })
      .execute();

    return body.results; // Returns an array of all active carts
  } catch (error) {
    console.error("Error fetching all customer carts:", error);
    return [];
  }
}

Use Custom Fields to differentiate Carts

In a multi-Cart scenario, consider Custom Fields to categorize Carts. In some B2B cases you might allow the customer to give each Cart a unique name, so that they can easily identify what each Cart is for.

Define a Custom Type: create a Custom Type for Carts (for example, cart-attributes) with a field like cartType (of type Enum or String).
Set the Custom Field value on creation: when creating a Cart, populate the Custom Field.

Example of creating a Cart with a Custom Typetypescript


const cartDraft: CartDraft = {
  customerId: customerId,
  currency: "USD",
  country: "US",
  custom: {
    type: { key: "cart-attributes", typeId: "type" },
    fields: {
      cartType: "B2B-Project-A",
    },
  },
};
// ... post the cartDraft

Query by Custom Field: add the custom field to your where predicate to find specific types of Carts.

Example of querying for a specific Cart typetypescript


const where = [
  `customerId="${customerId}"`,
  `cartState="Active"`,
  `custom(fields(cartType="B2B-Project-A"))`,
];

Find and manage existing Carts

Discover efficient methods for retrieving and managing customer Carts.

Construct the optimal query.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Step 1: Choose the right endpoint.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Step 2: Build the where predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Step 3: Add performance and consistency parameters.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Complete API request example.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Implementation with the SDK.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

How to enforce a single active Cart.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

How to handle multiple Carts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Use Custom Fields to differentiate Carts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Test your knowledge.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}