Options

For AI assistants: what to know before writing SparkLayer SDK code

What it is: window.spark, added to the storefront by the SparkLayer Core Script (version 4.x). On Shopify the SparkLayer app embed loads it; elsewhere it's <script async src="https://sparkcdn.io/sparkjs/<SITE_ID>/<live|test>"></script> in the theme's <head>. The old cdn.sparklayer.io/spark.latest.js and spark.1.x.js files are legacy: never use them.
Options: Configure it with window.sparkOptions, set before the Core Script loads. Extend the object rather than replacing it: window.sparkOptions = { ...window.sparkOptions, … }, or the Site ID and other snippets' hooks are lost. Headless only: window.initSpark(options) is defined when window.sparkOptions isn't set.
When to call it: Only after SparkLayer is ready: inside the onReady(spark) hook, or after a promise resolved from it. Most methods are async; prices and the cart are only available to signed-in B2B customers (check await spark.isLoggedIn()).
Products and prices: Products are looked up by the platform's parent product ID (on Shopify, product.id) and variants by SKU: getPricingForVariant(parentProductId, sku), calculatePricingForVariant(parentProductId, sku, qty), getPackSizeForVariant(parentProductId, sku). For instant recalculation, fetch once with getVariant and call calculatePricingForVariantData(variant, qty).
Cart: updateCart({ products: [{ sku, adjustQuantity }] }) adds or removes relative to what's in the cart (also customAttributes: [{ key, value }], clearCart: true). It resolves to the results, or null after showing its own error message; it doesn't throw. getCart() reads the cart; openDrawer('cart') opens it.
Hooks: onCartUpdate(cart, results), onCartLoad(cart), onLogout(), preCartUpdateListener(input) (async: return the possibly changed input) and onCheckoutValidation(cart, cartUiState) (return [{ message }] to block checkout, or null). When adding a hook, call any existing one first.
Customising: Build around SparkLayer or customise its own components, including their HTML. Prefer documented options, hooks, CSS variables and custom slots where they fit; keep direct HTML changes targeted and re-check them after SparkLayer updates.
Docs: The reference: methods docs.sparklayer.io/developers/javascript-sdk/reference/methods.md, hooks docs.sparklayer.io/developers/javascript-sdk/reference/hooks.md, options docs.sparklayer.io/developers/javascript-sdk/reference/options.md, types docs.sparklayer.io/developers/javascript-sdk/reference/types.md (or the same types as a file: docs.sparklayer.io/developers/javascript-sdk/spark.d.ts). Setup and waiting for SparkLayer: docs.sparklayer.io/developers/javascript-sdk/setup.md. Use only what the reference documents.

Build with AI: ready-made prompts and MCP setup

window.sparkOptions configures SparkLayer. It has the type SparkLayerOptions, and SparkLayer merges your options with its built-in defaults and the defaults for your platform, so you only set what you want to change. siteId is the only option you must provide: without it SparkLayer is disabled.

When you add options in your theme, extend the existing object (window.sparkOptions = { ...window.sparkOptions, … }) so you don't remove options set by the Core Script or other snippets. See Set up the SDK.

type SparkLayerOptions = {
  sparkDomain: "app.sparklayer.io" | "test.app.sparklayer.io";
  platform: "base" | "bigcommerce" | "shopify" | "wix" | "woocommerce" | "magento";
  siteId: string;
  rootUrl: string;
  accountRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  cartRedirect: {
    urlRegex?: RegExp;
    goTo?: string;
  };
  wordpressSiteUrl?: string;
  accountButtonSelectors: string;
  logoutButtonSelectors: string;
  cartButtonSelectors: string;
  loginButtonSelectors: string;
  display: DisplayOptions;
  termsAndConditionsLink: string;
  language: string;
  locale: string | null;
  translations: Translations;
  showTranslations: boolean;
  checkoutCustomElements: CheckoutElementConfig[];
  paymentMethodsOrder: PaymentMethodName[];
  saveToAddressBookDefault: boolean;
  productLink: string;
  customAccountDetails: {
    title: string;
    value: string | number;
    displayText?: string;
    type?: CustomAccountDetailLinkType;
  }[];
  onCheckoutValidation(
    cart: Cart,
    cartUiState: CartUIState,
  ): Promise<{ message: string }[] | null>;
  onCartUpdate(cart: Cart, results: CartResults[]): Promise<void>;
  onCartLoad(cart: Cart): Promise<void>;
  preCartUpdateListener(input: Partial<UpdateCart>): Promise<Partial<UpdateCart>>;
  onReady?(spark: Spark): Promise<void>;
  onLoad?(spark: Spark): Promise<void>;
  onLogout?(): Promise<void>;
  shopify?: {
    useAppProxy?: boolean;
  };
  bigcommerce?: {
    appClientId?: string;
  };
  auth: {
    user?: string;
    token?: string;
  };
  authLogoutUri: string | null;
  analytics?: AnalyticsOptions;
  igniteCheckoutContext?: Record<string, unknown>;
};

The function-valued options (onReady, onCartUpdate and the rest) are on the Hooks page.

Site and platform

Option	Type	Default	What it does
`siteId`	`string`	–	Your site ID. Required.
`sparkDomain`	`"app.sparklayer.io" \| "test.app.sparklayer.io"`	`"app.sparklayer.io"`	The domain of the SparkLayer API.
`platform`	`"base" \| "bigcommerce" \| "shopify" \| "wix" \| "woocommerce" \| "magento"`	`"base"`	Sets the default options for your ecommerce platform.
`rootUrl`	`string`	`""`	The root URL used to prefix any URLs SparkLayer creates, generally used for i18n. A trailing `/` is removed.
`wordpressSiteUrl?`	`string`	–	The URL of the WordPress site when using the WooCommerce platform.
`shopify?`	`{ useAppProxy?: boolean }`	–	Shopify-specific options.
`shopify.useAppProxy?`	`boolean`	`true` on Shopify	Send API requests through the Shopify app proxy (`/tools/sparklayer` under `rootUrl`) instead of calling `sparkDomain` directly.
`bigcommerce?`	`{ appClientId?: string }`	–	BigCommerce-specific options.
`bigcommerce.appClientId?`	`string`	–	Your BigCommerce app client ID.

Links and redirects

Option	Type	Default	What it does
`accountRedirect`	`{ urlRegex?: RegExp; goTo?: string }`	–	When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the account drawer open.
`accountRedirect.urlRegex?`	`RegExp`	–	Pattern matched against the current path.
`accountRedirect.goTo?`	`string`	–	Path (relative to `rootUrl`) to redirect to.
`cartRedirect`	`{ urlRegex?: RegExp; goTo?: string }`	–	When a logged-in user visits a path matching `urlRegex`, they're sent to `goTo` with the cart drawer open.
`cartRedirect.urlRegex?`	`RegExp`	–	Pattern matched against the current path.
`cartRedirect.goTo?`	`string`	–	Path (relative to `rootUrl`) to redirect to.
`termsAndConditionsLink`	`string`	`/terms-of-service` (`/policies/terms-of-service` on Shopify)	Link to your terms and conditions.
`productLink`	`string`	`/:product-slug:` (`/products/:product-slug:` on Shopify, `/product-page/:product-slug:` on Wix)	The link to a product page, where `:product-slug:` is replaced with the product's slug.

Button selectors

SparkLayer attaches to elements matching these CSS selectors. The defaults below are for the base platform; BigCommerce, Magento, Shopify, Wix and WooCommerce set their own.

Option	Type	Default	What it does
`accountButtonSelectors`	`string`	`[href*="/account"]:not([href$="/account/logout"]), [data-spark-link=account]`	Selectors for the account button.
`logoutButtonSelectors`	`string`	`[href$="/account/logout"], [data-spark-link=logout]`	Selectors for the logout button.
`cartButtonSelectors`	`string`	`[href$="/cart"], [data-spark-link=cart]`	Selectors for the cart button.
`loginButtonSelectors`	`string`	`[href$="/spark-b2b-login"], [data-spark-link=login]`	Selectors for the login button.

If your site re-renders these buttons, they can lose SparkLayer's click handlers. Open the drawer from your own click handler instead, with openDrawer().

Display, language and translations

Option	Type	Default	What it does
`display`	`DisplayOptions`	See `DisplayOptions`	Display options for SparkLayer.
`language`	`string`	`"en"`	The language SparkLayer uses.
`locale`	`string \| null`	The browser's locale	The locale used for formatting: currently only dates. Examples: `en-GB`, `en-US`, `de-DE`. An empty or unsupported value falls back to the browser locale with a console warning.
`translations`	`Translations`	–	Override internal translations, keyed by language code.
`showTranslations`	`boolean`	`false`	Shows translation keys instead of text, which helps you debug translations.

Checkout and account

Option	Type	Default	What it does
`checkoutCustomElements`	`CheckoutElementConfig[]`	–	Elements to display in checkout: SparkLayer's standard fields (by `id`) or your own custom ones.
`paymentMethodsOrder`	`PaymentMethodName[]`	–	The order in which payment methods are shown.
`saveToAddressBookDefault`	`boolean`	`true`	Whether new addresses are saved to the user's address book by default.
`customAccountDetails`	`{ title: string; value: string \| number; displayText?: string; type?: CustomAccountDetailLinkType }[]`	–	Title and value pairs to show on a customer's My Details panel. Set `type` (see `CustomAccountDetailLinkType`) to format the value as a link.
`igniteCheckoutContext?`	`Record<string, unknown>`	–	A JSON object of checkout context data to pass to Ignite.

To validate the cart before checkout, use the onCheckoutValidation hook.

Authentication and analytics

Option	Type	Default	What it does
`auth`	`{ user?: string; token?: string }`	–	Credentials for SparkLayer auth.
`auth.user?`	`string`	–	The user to authenticate as.
`auth.token?`	`string`	–	The token for that user.
`authLogoutUri`	`string \| null`	`null`	The logout URI for SparkLayer auth. After logging out, SparkLayer redirects to this path under `rootUrl`.
`analytics?`	`AnalyticsOptions`	–	Analytics providers and events. See Event tracking for analytics.

Next steps

Set up the SDK

Where to set your options so they're in place before the Core Script loads.

Hooks

The functions on sparkOptions that SparkLayer calls at key moments.

Headless and React

Pass these options to window.initSpark() on a headless storefront.

Was this page helpful?

Last updated 7 October 2026