Create Cart in the Storefront

In this guide, you'll learn how to create and store a cart in your storefront.

For the recommended Next.js App Router pattern (server actions, cookies, store code vs country), see Build a Next.js Storefront.

Create Cart on First Access

Create a cart the first time a customer needs one (add to cart, open the cart page, or start checkout). Persist the cart ID in an httpOnly cookie (_aiminaabee_cart_id in the Next.js template). Do not use localStorage on Next.js App Router.

To create a cart, send a request to the Create Cart API route.

Next.js (recommended)

Put this in src/lib/data/cart.ts with "use server". Resolve the region from the URL country, not from the store code:

1"use server"
2
3export async function getOrSetCart(storeCode: string, countryCode: string) {
4  const region = await getRegion(storeCode, countryCode)
5
6  if (!region) {
7    throw new Error(`Region not found for country code: ${countryCode}`)
8  }
9
10  let cart = await retrieveCart(storeCode)
11  const headers = { ...(await getAuthHeaders()) }
12
13  if (!cart) {
14    const { cart: createdCart } = await sdk.store.cart.create(
15      storeCode,
16      { region_id: region.id },
17      {},
18      headers
19    )
20    await setCartId(createdCart.id)
21    revalidateTag(await getCacheTag("carts"))
22    cart = createdCart
23  }
24
25  if (cart.region_id !== region.id) {
26    await sdk.store.cart.update(
27      storeCode,
28      cart.id,
29      { region_id: region.id },
30      {},
31      headers
32    )
33    revalidateTag(await getCacheTag("carts"))
34  }
35
36  return cart
37}

setCartId writes _aiminaabee_cart_id. getAuthHeaders reads _aiminaabee_jwt. Both live in src/lib/data/cookies.ts.

Call getOrSetCart(storeCode, countryCode) from add-to-cart and checkout — not from a client useEffect on every page.

JS SDK

1sdk.store.cart.create(storeCode, {
2  region_id: region.id,
3})
4.then(({ cart }) => {
5  // persist cart.id (httpOnly cookie on Next.js)
6})

The response of the Create Cart API route has a cart field, which is a cart object.

Refer to the Create Cart API reference for details on other available request parameters.

Cart Currency

A cart's currency is set from the region you associate it with. If you pass a currency_code when creating a cart, it must match the region's currency. Otherwise, an error is thrown.

To avoid errors, omit currency_code and let Aiminaabee set it from the region automatically.

Cart's Sales Channel Scope

Always pass the publishable API key in the header of the request (the JS SDK does this automatically, as explained in Publishable API Keys). Aiminaabee associates the cart with the sales channel(s) of that key.

This scopes the products you retrieve, available inventory, and the sales channel of the order created from the cart. If you want a different sales channel, or the key has several and you need to pick one, pass sales_channel_id to the Create Cart API route.

1sdk.store.cart.create(storeCode, {
2  region_id: region.id,
3  sales_channel_id: "sc_123",
4})
5.then(({ cart }) => {
6  console.log(cart)
7})

Associate Customer with Cart

When the cart is created for a logged-in customer, it's automatically associated with that customer.

If the cart was created for a guest, then the customer logs in, transfer the cart as explained in Update Cart. On Next.js, call transferCart(storeCode) after setAuthToken.

Set Cart's Locale

By default, items in the cart use the product's original content. If your storefront supports localization, set the cart's locale so item contents match the customer's language.

Pass locale to the Create Cart API route:

1sdk.store.cart.create(storeCode, {
2  region_id: region.id,
3  locale: "fr-FR",
4})
5.then(({ cart }) => {
6  console.log(cart)
7})

When the locale is set, cart items use that locale if translations exist. You can also update the cart's locale later.

Store Cart Details in React Context

A React context that creates the cart in useEffect is for SPAs only. On Next.js App Router, keep the cart ID in the cookie and load the cart in server components or server actions. See Cart React Context.