Skip to main content

​
NPM Package

@commercengine/checkout

SolidJS integration for Commerce Engine Checkout.

​
Installation

npm install @commercengine/checkout

​
Setup

Call initCheckout once at your app’s entry point. The SDK resolves the hosted URL from storeId + environment using store-specific subdomains:
index.tsx
import { render } from "solid-js/web";
import { initCheckout } from "@commercengine/checkout/solid";
import App from "./App";

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

render(() => <App />, document.getElementById("root")!);

​
Use the primitive

useCheckout() returns an object with reactive getters (powered by Solid signals) and action methods:
CartButton.tsx
import { useCheckout } from "@commercengine/checkout/solid";

function CartButton() {
  const checkout = useCheckout();

  return (
    <button onClick={checkout.openCart} disabled={!checkout.isReady}>
      Cart ({checkout.cartCount})
    </button>
  );
}
Each property on the returned object is a getter backed by a Solid signal. Components only re-render when the specific values they access change.
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.

​
Fine-grained signals

For minimal subscriptions, use the individual signal creators:
CartBadge.tsx
import { createCartCountSignal } from "@commercengine/checkout/solid";

function CartBadge() {
  const cartCount = createCartCountSignal();
  return <span class="badge">{cartCount()}</span>;
}
Available signal creators: createCartCountSignal, createIsReadySignal.

​
Full example

App.tsx
import { Show } from "solid-js";
import { initCheckout, useCheckout } from "@commercengine/checkout/solid";

initCheckout({
  storeId: "store_xxx",
  apiKey: "ak_xxx",
  environment: "production",
  onComplete: (order) => {
    window.location.href = `/thank-you?order=${order.orderNumber}`;
  },
});

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

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

function ProductPage() {
  const { addToCart } = useCheckout();

  return (
    <button onClick={() => addToCart("product_abc", "variant_xyz")}>
      Add to Cart
    </button>
  );
}

export default function App() {
  return (
    <>
      <Navbar />
      <ProductPage />
    </>
  );
}

​
SolidStart

For SolidStart, initialize in the root layout. The SDK no-ops during SSR.
root.tsx
import { initCheckout } from "@commercengine/checkout/solid";

if (typeof window !== "undefined") {
  initCheckout({
    storeId: "store_xxx",
    apiKey: "ak_xxx",
    environment: "production",
  });
}

​
Primitive API reference

useCheckout() returns:
PropertyTypeDescription
isReadyboolean (reactive getter)true when the checkout iframe is loaded
isOpenboolean (reactive getter)true when the overlay is visible
cartCountnumber (reactive getter)Number of items in the cart
cartTotalnumber (reactive getter)Cart subtotal
cartCurrencystring (reactive getter)Currency code
isLoggedInboolean (reactive getter)Whether a user is logged in
userUserInfo | null (reactive getter)Current user info
openCart()functionOpen the cart drawer
openCheckout()functionOpen checkout directly
close()functionClose the overlay
addToCart(productId, variantId, quantity?)functionAdd an item to the cart
updateTokens(accessToken, refreshToken?)functionSync auth tokens