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. |
environment | "production" | "staging" | "production" | Determines which checkout app URL is loaded. |
url | string | — | Override the checkout URL. Useful for local development (e.g. http://localhost:8080). |
Appearance
| Option | Type | Default | Description |
|---|
theme | "light" | "dark" | "system" | "system" | Theme preference for the checkout UI. |
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. |
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. |
Feature Flags
| Option | Type | Default | Description |
|---|
features.loyalty | boolean | true | Show loyalty points redemption. |
features.coupons | boolean | true | Show coupon code input. |
features.collectInStore | boolean | false | Enable collect-in-store fulfillment option. |
features.freeShippingProgress | boolean | true | Show free shipping progress bar. |
features.productRecommendations | boolean | true | Show product recommendations in cart. |
Callbacks
| Callback | Payload | Description |
|---|
onReady | — | Checkout iframe is loaded and ready. |
onOpen | — | Checkout overlay became visible. |
onClose | — | Checkout overlay was closed. |
onComplete | { id, orderNumber } | Order was placed successfully. |
onCartUpdate | { count, total, currency } | Cart contents changed. |
onLogin | { accessToken, refreshToken, user, loginMethod } | User logged in. loginMethod is "whatsapp", "phone", or "email". |
onLogout | { accessToken, refreshToken, user } | User logged out. |
onTokenRefresh | { accessToken, refreshToken } | Tokens were automatically refreshed. |
onSessionError | — | Session became invalid. All tokens are cleared. |
onError | { message } | A configuration or runtime error occurred. |
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. |
destroy() | Remove the iframe and clean up all listeners. Vanilla JS only. |
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:login | { accessToken, refreshToken, user, loginMethod } | User logged in. |
auth:logout | { accessToken, refreshToken, user } | User logged out. |
auth:refresh | { accessToken, refreshToken } | Tokens refreshed. |
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);
Environment URLs
| Environment | Checkout App URL |
|---|
production | https://checkout.commercengine.com |
staging | https://staging.checkout.commercengine.com |
https://cdn.commercengine.com/v1.js (single deployment). The environment option only changes which checkout app URL is loaded inside the iframe.
