Init options
These options are passed to initCheckout() (framework SDKs) or Commercengine.init() / new Checkout() (vanilla JS).
Credentials
| Option | Type | Default | Description |
|---|
storeId | string | — | Your Commerce Engine Store ID. Required unless url is provided. |
apiKey | string | — | Your Commerce Engine API Key. Required unless url is provided (or already embedded in url). |
environment | "production" | "staging" | "production" | Determines which subdomain pattern is used: https://{storeId}.checkout.commercengine.com or https://{storeId}.staging.checkout.commercengine.com. |
url | string | — | Override checkout host resolution (local dev, preview builds, custom domains). If host is localhost and storeId is passed, SDK rewrites to a store-scoped host automatically. |
Appearance
| Option | Type | Default | Description |
|---|
theme | "light" | "dark" | "system" | "system" | Per-session theme override for checkout UI. Primary visual config is managed in Checkout Studio. |
appearance.zIndex | number | 99999 | z-index for the checkout overlay container. |
Authentication
| Option | Type | Default | Description |
|---|
authMode | "managed" | "provided" | "managed" | "managed": checkout handles its own auth. "provided": your app manages tokens and syncs them to checkout (recommended when your storefront already uses Storefront SDK auth). |
accessToken | string | — | Initial access token (JWT). Used with authMode: "provided". |
refreshToken | string | — | Initial refresh token. Used with authMode: "provided". |
When to use authMode: "provided"Use this when your app already has its own login system and you want checkout to share the same session. Pass tokens at init and call updateTokens() when they change.
Quick Buy
| Option | Type | Default | Description |
|---|
quickBuy | object | — | Open checkout directly for a specific product. |
quickBuy.productId | string | — | Product ID. Required when using quickBuy. |
quickBuy.variantId | string | null | — | Variant ID, or null for products without variants. Required when using quickBuy. |
quickBuy.quantity | number | 1 | Quantity to add. |
sessionMode | "continue-existing" | "force-new" | "continue-existing" | Whether to continue the user’s existing cart or start fresh. |
autoDetectQuickBuy | boolean | false | Automatically detect quick buy params from the parent URL. The SDK will clean up the URL params after detection. |
Managed in Checkout Studio
The following settings are configured remotely in Checkout Studio (Config API) and injected into checkout on each page load:
- Feature flags (
loyalty, coupons, collectInStore, freeShippingProgress, productRecommendations)
- Login configuration (enabled methods, account switch behavior)
- Drawer direction (mobile/desktop)
- Payment provider selection
- Brand appearance tokens (colors, typography, shape system, sizing)
These are intentionally not part of the SDK init options.
Configuration precedence (source of truth)
| Setting | Primary source | Runtime override | Notes |
|---|
| Features, login methods, drawer direction, payment provider, appearance tokens | Checkout Studio | None via SDK init options | Saved config is fetched and applied by Hosted Checkout |
| Theme mode | Checkout Studio default (ui.theme) | theme in SDK init | SDK theme is a per-session override |
| Auth tokens | Parent app / checkout auth flow | accessToken, refreshToken, updateTokens() | Depends on authMode |
| Quick buy behavior | SDK init options / parent URL (if auto-detect enabled) | quickBuy, sessionMode, autoDetectQuickBuy | Request-scoped behavior |
| Checkout host resolution | storeId + environment | url | url fully overrides host resolution |
Methods
These methods are available on the checkout instance (vanilla JS) or returned by the framework hook/composable.
| Method | Description |
|---|
openCart() | Open the cart drawer. |
openCheckout() | Open the checkout directly, skipping the cart drawer. |
close() | Close the checkout overlay. |
addToCart(productId, variantId, quantity?) | Add an item. variantId can be null. quantity defaults to 1. |
updateTokens(accessToken, refreshToken?) | Sync auth tokens from your app into checkout. |
getCart() | Returns { count, total, currency }. Vanilla JS only. |
getTokens() | Returns latest { accessToken, refreshToken } received via auth:tokens-updated, or null if not received yet. Vanilla JS only. |
destroy() | Remove the iframe and clean up all listeners. Vanilla JS only. |
Runtime properties (vanilla JS)
| Property | Type | Description |
|---|
ready | boolean | true when iframe initialization has completed (or surfaced an error state). |
open | boolean | true when the checkout overlay is visible. |
Events
When using the vanilla JS SDK (@commercengine/js), you can listen to events with checkout.on(event, handler):
| Event | Payload | Description |
|---|
ready | — | Iframe loaded and ready. |
open | — | Overlay became visible. |
close | — | Overlay was closed. |
complete | { id, orderNumber } | Order placed. |
cart:updated | { count, total, currency } | Cart changed. |
auth:tokens-updated | { accessToken, refreshToken } | Tokens changed (anonymous auth, login, logout, refresh). |
auth:login | { user, loginMethod } | User logged in (semantic event). |
auth:logout | { user } | User logged out (semantic event). |
auth:session-error | — | Session invalid, tokens cleared. |
error | { message } | Error occurred. |
checkout.on("complete", (order) => {
console.log("Order:", order.orderNumber);
});
// Listen once
checkout.once("ready", () => {
console.log("Checkout loaded");
});
// Remove listener
const handler = (cart) => console.log(cart.count);
checkout.on("cart:updated", handler);
checkout.off("cart:updated", handler);
Recommended token sync pattern (Storefront SDK + Hosted Checkout)
If your storefront already uses @commercengine/storefront-sdk, run Hosted Checkout in provided mode and wire token sync both ways:
import StorefrontSDK, { BrowserTokenStorage } from "@commercengine/storefront-sdk";
import { initCheckout, getCheckout } from "@commercengine/checkout";
const tokenStorage = new BrowserTokenStorage("ce_");
const storefront = new StorefrontSDK({
storeId: "store_xxx",
apiKey: "ak_xxx",
tokenStorage,
onTokensUpdated: (accessToken, refreshToken) => {
// SDK -> checkout
getCheckout().updateTokens(accessToken, refreshToken);
},
});
const accessToken = await tokenStorage.getAccessToken();
const refreshToken = await tokenStorage.getRefreshToken();
initCheckout({
storeId: "store_xxx",
apiKey: "ak_xxx",
authMode: "provided",
accessToken: accessToken ?? undefined,
refreshToken: refreshToken ?? undefined,
onTokensUpdated: ({ accessToken, refreshToken }) => {
// checkout -> SDK
storefront.setTokens(accessToken, refreshToken);
},
});
Environment URLs
| Environment | Checkout App URL Pattern |
|---|
production | https://{storeId}.checkout.commercengine.com |
staging | https://{storeId}.staging.checkout.commercengine.com |
https://cdn.commercengine.com/v1.js (single deployment). The environment option selects the hostname pattern, and storeId is encoded in the subdomain.
