Theme SDK overview

window.cartisto — the client-side API façade every theme talks to.

The Theme SDK is window.cartisto: a thin, credentialed façade over the store API plus a little shared client state. It is loaded by {{ platform_body | raw }} before your main.js, so your presentation scripts can rely on it.

window.cartisto
  .state     observable store: cart, wishlistIds, customer, currency, locale
  .ui        controller registry: register / scan / ref
  .events    the one event API: on / off / emit
  .utils     formatPrice, langUrl, escapeHtml, productUrl, isSellable, …
  .cart .product .wishlist … API namespaces (below)

API namespaces

Every namespace method returns a promise of the standard envelope { success, message, data }. The SDK owns credentials, the silent 401 → refresh → retry, and the guest-session mint — you never handle tokens.

auth · address · product · review · wishlist · category · bundles · marketing · recommendations · loyalty · credit · cart · order · customer · lang · currency · newsletter · refund · invoice · shipping · payment · geo

const res = await cartisto.cart.get();
if (res.success) render(res.data);

await cartisto.wishlist.toggle(productId);
await cartisto.newsletter.subscribe(email);

Danger

Never call the API directly A theme must not call fetch / XHR. Networking, auth refresh, and the error shape live in the SDK so they stay in one place. The Quality Gate rejects a theme that calls fetch.

TypeScript types

cartisto.d.ts is the type contract for window.cartisto and the platform globals. Point your editor at it for autocomplete:

/// <reference path="cartisto.d.ts" />

How you attach behavior

You have exactly two tools, chosen by who renders the UI:

Controllers bind behavior to markup you write (the preferred model).
Components are custom elements the platform renders; you place the tag and style it.

And two ways to observe change — both on the Events & state page:

State — read/subscribe to shared client state (cartisto.state).
Events — react to cart/variant/wishlist changes.

The stable seam

At launch, the data-cartisto grammar, the event names, cartisto.state / cartisto.ui, the seed globals, and the bundle URL scheme all freeze as v1. After that, changes are additive; a breaking change ships a new SDK major and your theme opts in via theme.json’s "sdk" field. See Versioning.