Storefront JavaScript API

Storefront JavaScript API

Overview

Appify CPO 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 Appify CPO 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 Appify CPO 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 ...

    • How customers use the Product Designer (storefront)

      Overview When a customer clicks your Product Designer button, a full-screen editor opens with their current calculator option values applied (artboard size, background, bound product image, and so on). This page walks through the customer experience ...

    • Add to Cart Button Settings

      Overview Appify CPO 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, Appify CPO detects the button automatically. If auto-detection doesn't work — or ...

    • 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 Appify CPO on Your Theme

      Overview Before your calculators can appear on your storefront, you need to enable Appify CPO 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 ...