Storefront JavaScript API

Storefront JavaScript API

Overview

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

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

    • Multi-Select Options

      Overview Options that allow multiple selections—checkboxes, multi-file uploads, or multi-select swatches—can display multiple layers on the product image. You choose between Slots (filled in order) or Per value (each value has a fixed spot). Each ...