Implement the Cart module

InStore Add-On
Ask about this Page
Copy for AI
View as Markdown

Read the Cart state from the InStore State module, and render a Cart that replaces the one built into the InStore POS.

This page covers the interface that a Cart replacement module implements. For the build setup that every replacement module needs, see Build a replacement module.

A Cart replacement module reads everything it needs from the Cart module context, rather than calling the InStore backend.

Read Cart state and operations

Import useCartModuleContext from instoreState/context/CartModuleContext to read the Cart state and its operations.
useCartModuleContext returns a context object with the following public properties and methods. They are marked @public in the types that the InStore State module publishes, and are supported for use in replacement modules. To resolve those types, see Build a replacement module.
MemberTypeDescription
cartCart | nullActive Cart, or null when no Cart has been started.
checkCartParameterMethodChecks whether a configuration parameter is available for this workstation.
checkUserPermissionMethodChecks whether the signed-in user holds a given permission.
getCartMethodLoads a Cart by key and makes it the active Cart.
isCheckoutAvailablebooleanWhether the Cart can go to checkout. false while a Cart action, such as adding an item, attaching a customer, or a queued barcode, is in flight.
localestringActive locale, such as en-GB.
updateCartMethodApplies Cart update actions to a Cart. Accepts all Cart update actions.
updateLineItemQtyMethodSets the quantity of a Line Item on a Cart. A quantity of 0 or less removes the Line Item. Always writes the takeWith fulfillment. Applying it to an ordered line converts the line to take-with.

Render a minimal Cart

Expose a root component that defines your routes:

src/App.tsxtsx
import React from 'react';
import { Route, Routes } from 'react-router-dom';

import { CartPage } from './components/CartPage';

const App = () => (
  <Routes>
    <Route index element={<CartPage />} />
  </Routes>
);

export default App;

Then read the context and render the Cart:

src/components/CartPage.tsxtsx
import { useConfigurationContext } from 'instoreState/configuration/context';
import { useCartModuleContext } from 'instoreState/context/CartModuleContext';
import { useLocalizationContext } from 'instoreState/locale';
import React from 'react';

export const CartPage = () => {
  const { t } = useLocalizationContext();
  const { navigate } = useConfigurationContext();
  const { cart, isCheckoutAvailable, updateLineItemQty } =
    useCartModuleContext();

  if (!cart) {
    return <p>{t('Cart.line_items.no_items')}</p>;
  }

  return (
    <div>
      {cart.lineItems.map((item) => (
        <div key={item.id}>
          <span>{item.name}</span>
          <span>{item.totalPriceDinero.toFormat()}</span>
          <button onClick={() => updateLineItemQty(cart.key, item.id, 0)}>
            {t('Cart.line_items.actions.remove')}
          </button>
        </div>
      ))}
      <span>{cart.totals.totalPriceDinero.toFormat()}</span>
      <button
        disabled={!isCheckoutAvailable}
        onClick={() => navigate('/checkout')}
      >
        {t('Cart.totals.button')}
      </button>
    </div>
  );
};

Cart behavior to account for

A Cart arrives ready to display, so your module never handles a raw commercetools payload. Account for the following behavior:

  • Money arrives as Dinero values. Format them with .toFormat() instead of reading centAmount.
  • Totals are precomputed on cart.totals.
  • Line Item names resolve by exact match on the active locale, and fall back to an empty string. The POS applies no locale fallback chain.
useCartModuleContext is not activated if you run the module outside of the InStore POS. The Cart context returns empty state, and operations do not work. If Line Items do not appear in your Cart, verify that you have connected the module correctly to the InStore POS.
The Cart module context covers reading the Cart, updating Line Item quantities, and checking out. The built-in module also applies coupons and item-level discounts, saves Cart contents to a wishlist, and captures shipping details for an attached Customer, which the context does not expose as dedicated operations. A replacement module implements those surfaces itself using updateCart. For the full set of built-in capabilities, see InStore_Cart.

Next steps

Use the following resources to finish and roll out your Cart module: