Implement the Cart module

InStore Add-On
Ask about this Page
Copy for LLM
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 describes the technical interface requirements for a Cart replacement. For the build setup that every replacement module needs, see Build a replacement module.

A Cart replacement 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 InStore State library TypeScript documentation and are supported for use in replacement modules.
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.

Next steps

Use the following resources to continue developing your Cart module: