CartistoDocs
⌕

Platform vs. theme

The dividing line that keeps commerce correct and themes free.

Cartisto draws a hard line between commerce behavior and presentation. Understanding it is the difference between a theme that survives platform updates and one that breaks on every release.

Who owns what

Concern Owner Where it lives
API calls, cart / wishlist / variant logic, offer maths, pricing Platform The SDK (window.cartisto), bundled and served by the platform
Which widget appears where on the page Theme Liquid templates
How everything looks Theme Theme CSS / Tailwind
The checkout & order-confirmation pages Platform Locked pages — a theme can’t edit or ship them

The server is the durable service layer: it computes every price and enforces the money path. The client SDK is a thin façade over that API — never a second copy of the rules.

Why the line is drawn here

Three properties fall out of it, and all three matter:

  1. Fix once, every theme updates. A bug in add-to-cart is fixed in the SDK bundle. Because bundles are content-hashed and served with a long cache plus instant invalidation, returning shoppers get the fix immediately — across every theme, with no theme edits.
  2. The money path can’t be tampered with. Checkout and order-confirmation render from platform-owned templates in a platform-owned layout. No theme <script>, and no merchant custom JS, runs on the payment surface.
  3. Themes stay simple. A theme is markup + styling + a little presentation JS. It never re-implements commerce, so it can’t get commerce wrong.

The two attachment models

The platform attaches behavior to your markup in exactly two ways:

  • Controllers enhance markup you write. You place a data-cartisto="…" marker; the platform binds behavior to it. You keep full control of layout and classes. This is the preferred model. See Controllers.
  • Custom elements render UI the platform owns (e.g. <cartisto-bundles>). You place the tag and style the result. See Components.

What a theme must never do

  • Call fetch / XHR directly — use a cartisto.* SDK method.
  • Re-implement commerce rules (pricing, discounts, stock).
  • Ship the checkout / order-confirmation pages.
  • Hardcode a platform <script src> — the platform injects those.
Warning

These aren’t style guidelines The Quality Gate mechanically rejects a publish that breaks the rules above. It runs in the CLI, in tests, and on the server publish path — you can’t ship around it.