Storefront JavaScript API

Storefront JavaScript API

Overview

Calculator AI exposes a browser-only integration surface on the storefront: your theme JavaScript, or another Shopify app’s script on the same page, can listen for calculator updates and set option values programmatically. There is no secret API key—the same rules apply as for any custom JavaScript on your storefront (protect against XSS).

Use this page for a quick orientation. The full payload tables, error codes, and edge cases are documented for developers in the Calculator AI repository at docs/storefront-calculator-api.md (Storefront JavaScript API contract).

What you can do

  1. Listen for calc:ready and calc:change on document to read detail.values and detail.spec.
  2. Set a value with either:
    • window.CalcAI.setValue({ optionId, value, instanceId?, calculatorId? }) (returns { ok, error?, code? }), or
    • document.dispatchEvent(new CustomEvent('calcai:setValue', { bubbles: false, detail: { ... } })).

Wait until window.CalcAI?.setValue is a function (after the calculator module loads), or listen for calc:ready first.

Multi-calculator pages

If more than one calculator is on the page, pass instanceId and/or calculatorId from calc:ready (or bootstrap JSON). On a single calculator page, those fields are often null and the API still resolves the only instance.

External updates and feedback loops

When a change is applied via the public API, the next calc:change has detail.external === true and reason === 'external-set'. Use that to avoid echoing programmatic updates back into a chat or analytics pipeline.

Limitations

  • File and modal option types cannot be set through this API.
  • If the storefront loads a fallback runtime without the full renderer, the public set API is unavailable (NO_CALC_INSTANCE). Normal theme blocks use the full renderer.

Examples

Listen for live values:

document.addEventListener("calc:change", (ev) => {
  const { values, spec, external } = ev.detail || {};
  if (!external) {
    // shopper-driven change
  }
});

Set a value (after CalcAI is available):

const out = window.CalcAI?.setValue({
  optionId: "my_option_key",
  value: "42",
});
if (!out?.ok) console.warn(out?.code, out?.error);

    • Related Articles

    • Custom JavaScript

      Overview Calculator AI allows you to add custom JavaScript to your calculator for advanced use cases that go beyond built-in configuration. You can run code when the calculator first loads (global scripts) or when a specific option's value changes ...

    • Add to Cart Button Settings

      Overview Calculator AI works with your theme's Add to Cart button to include the calculated price and customer selections when an item is added to the cart. In most themes, Calculator AI detects the button automatically. If auto-detection doesn't ...

    • Calculator Editor Overview

      Overview The calculator editor is the main workspace where you build and customize your product calculator. It is divided into three areas: a header bar at the top, a tabbed main panel in the center, and a live preview panel on the right. Together, ...

    • Installing Calculator AI on Your Theme

      Overview Before your calculators can appear on your storefront, you need to enable Calculator AI in your Shopify theme. This is a one-time setup that takes a couple of minutes. After completing these steps, your theme will be ready to display ...

    • Theme App Extension

      For step-by-step instructions on adding blocks to your theme, see Adding Theme Blocks. Overview The Calculator AI theme app extension is what connects your calculators to your storefront. It provides an app embed and a set of theme blocks that you ...