Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
PropertyTypeDescription
isReadybooleantrue when the checkout iframe is loaded and ready
isOpenbooleantrue when the checkout overlay is visible
cartCountnumberNumber of items in the cart
cartTotalnumberCart subtotal
cartCurrencystringCurrency code (e.g. "INR")
isLoggedInbooleanWhether a user is logged in
userUserInfo | nullCurrent user info (decoded from JWT)
openCart()functionOpen the cart drawer
openCheckout()functionOpen checkout directly (skips cart)
close()functionClose the overlay
addToCart(productId, variantId, quantity?)functionAdd an item to the cart
updateTokens(accessToken, refreshToken?)functionSync auth tokens from your app