React - Commerce Engine Docs

NPM Package

@commercengine/checkout

React integration for Commerce Engine Checkout.

Installation

npm install @commercengine/checkout

Setup

Call initCheckout once at your app’s entry point. This creates a hidden iframe in the background — it does not block rendering. The SDK resolves the hosted URL from storeId + environment using store-specific subdomains.

App.tsx

import { initCheckout } from "@commercengine/checkout/react";

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  environment: "production",
});

initCheckout should be called once at the top level of your app, outside of any component. It is safe to call in SSR environments — it no-ops on the server.

Feature flags, login methods, drawer direction, and payment provider are managed in Checkout Studio (Config API), not as SDK init options. Use theme only for per-session overrides.

Use the hook

useCheckout() returns reactive state and action methods. No context provider is needed.

CartButton.tsx

import { useCheckout } from "@commercengine/checkout/react";

function CartButton() {
  const { openCart, cartCount, isReady } = useCheckout();

  return (
    <button onClick={openCart} disabled={!isReady}>
      Cart ({cartCount})
    </button>
  );
}

Full example

App.tsx

import { useEffect } from "react";
import { initCheckout, useCheckout } from "@commercengine/checkout/react";

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  environment: "production",
  onComplete: (order) => {
    console.log("Order placed:", order.orderNumber);
  },
});

function Navbar() {
  const { openCart, cartCount, isReady, isLoggedIn, user } = useCheckout();

  return (
    <nav>
      {isLoggedIn && <span>Hi, {user?.firstName}</span>}
      <button onClick={openCart} disabled={!isReady}>
        Cart ({cartCount})
      </button>
    </nav>
  );
}

function ProductPage({ productId, variantId }) {
  const { addToCart } = useCheckout();

  return (
    <button onClick={() => addToCart(productId, variantId)}>
      Add to Cart
    </button>
  );
}

export default function App() {
  return (
    <>
      <Navbar />
      <ProductPage productId="product_abc" variantId="variant_xyz" />
    </>
  );
}

Next.js

For Next.js, call initCheckout in a client component:

providers.tsx

"use client";

import { initCheckout } from "@commercengine/checkout/react";

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  environment: "production",
});

export function CheckoutProvider({ children }: { children: React.ReactNode }) {
  return <>{children}</>;
}

layout.tsx

import { CheckoutProvider } from "./providers";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <CheckoutProvider>{children}</CheckoutProvider>
      </body>
    </html>
  );
}

Then use useCheckout() in any client component as usual.

Syncing external auth

If your app manages its own authentication, pass tokens to keep checkout in sync:

import { useCheckout } from "@commercengine/checkout/react";

function AuthSync({ accessToken, refreshToken }) {
  const { updateTokens } = useCheckout();

  useEffect(() => {
    if (accessToken) {
      updateTokens(accessToken, refreshToken);
    }
  }, [accessToken, refreshToken]);

  return null;
}

Set authMode: "provided" in the init config when using external auth:

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  authMode: "provided",
  accessToken: "...",
  refreshToken: "...",
});

Hook API reference

useCheckout() returns:

Property	Type	Description
`isReady`	`boolean`	`true` when the checkout iframe is loaded and ready
`isOpen`	`boolean`	`true` when the checkout overlay is visible
`cartCount`	`number`	Number of items in the cart
`cartTotal`	`number`	Cart subtotal
`cartCurrency`	`string`	Currency code (e.g. `"INR"`)
`isLoggedIn`	`boolean`	Whether a user is logged in
`user`	`UserInfo \| null`	Current user info (decoded from JWT)
`openCart()`	`function`	Open the cart drawer
`openCheckout()`	`function`	Open checkout directly (skips cart)
`close()`	`function`	Close the overlay
`addToCart(productId, variantId, quantity?)`	`function`	Add an item to the cart
`updateTokens(accessToken, refreshToken?)`	`function`	Sync auth tokens from your app

​NPM Package

@commercengine/checkout

​Installation

​Setup

​Use the hook

​Full example

​Next.js

​Syncing external auth

​Hook API reference

NPM Package

Installation

Setup

Use the hook

Full example

Next.js

Syncing external auth

Hook API reference