Shopify

Shopify themes, apps & checkout

The single authoritative skill for building and customizing a Shopify store. The mental model: a Shopify store is a hosted platform you extend at well-defined seams — never a server you control. You render on the storefront with Liquid, you mutate data through the versioned GraphQL Admin API, and you customize checkout through sandboxed extensions. The platform owns hosting, the database, PCI scope, and the checkout DOM; you own only the seams. Three surfaces, three toolchains — name the surface before you write a line of code.

Pinned stack (verify against shopify.dev before pinning in a repo):

• Shopify CLI 4.x — auto-upgrades via the package manager it was installed with; skips CI, project-local installs, and major bumps. shopify app config push is removed; use shopify app deploy.
• GraphQL Admin API 2026-04 — latest stable; supported window 2026-04 / 2026-01 / 2025-10 / 2025-07†. Each version is supported ~12 months. Pin apiVersion and bump quarterly. † 2025-07 is at the edge of its window — accessible only until 2026-07-16; treat it as sunsetting and do not pin it in new work. Re-check the live list at shopify.dev/docs/api/usage/versioning.
• Remix app template (@shopify/shopify-app-remix, App Bridge, Polaris React). GraphQL > REST — REST Admin API is legacy; Shopify steers all new app work to GraphQL.
• Dawn — Shopify's source-available reference theme; OS 2.0 architecture is the baseline.

Pick your surface first

Most Shopify mistakes are surface confusion — answering with a headless React build when the ask was a Liquid section, or editing checkout.liquid when the seam is now an extension. Branch here:

If the answer is "the React rendering layer of a headless storefront", that is ../nextjs/SKILL.md, not this skill — Shopify is only the data seam (Storefront API) there.

Theme surface — Online Store 2.0 architecture

OS 2.0 (GA 2021, sometimes marketed "3.0") is the architecture: JSON templates + sections- everywhere + theme blocks + @app blocks + dynamic sources. The file map:

layout/theme.liquid            # the HTML shell (one per theme)
templates/product.json         # JSON template: which sections render, in what order
sections/main-product.liquid   # a section: markup + {% schema %} of merchant settings
sections/*.liquid              # section groups (header/footer) live here too
blocks/*.liquid                # theme blocks (reusable, nestable) — OS 2.0
snippets/*.liquid              # partials rendered via {% render %}
config/settings_schema.json    # global theme settings

Rule: every section carries a {% schema %} with presets so merchants edit content in the theme editor without a deploy. The why: content belongs in section.settings and metafields, not in code — if a merchant has to ask you to change a headline, the section is built wrong.

<!-- Bad: copy hardcoded in Liquid; merchant can't touch it -->
<h2>Summer Sale — 20% off everything</h2>

<!-- Good: editable in the theme editor, with a preset so it appears in "Add section" -->
<h2>{{ section.settings.heading | escape }}</h2>
{% schema %}
{
  "name": "Promo banner",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Summer Sale" }
  ],
  "blocks": [{ "type": "@app" }],
  "presets": [{ "name": "Promo banner" }]
}
{% endschema %}

The { "type": "@app" } block lets merchant-installed apps drop content into your section. The Shopify Theme Store requires the main product and featured-product sections to support @app blocks. See references/liquid-themes.md for setting types, section groups, and dynamic sources.

Liquid rules

• {% render %}, never {% include %}. render is scoped (the snippet only sees what you pass) and cacheable; include leaks the parent scope and is deprecated.

  {% comment %} Bad {% endcomment %}
  {% include 'price' %}
  {% comment %} Good — explicit, scoped, cacheable {% endcomment %}
  {% render 'price', product: product, variant: variant %}
  

• Bound every collection loop with limit: and never nest unbounded loops — storefront render cost is real and slow pages cost conversions. {% for p in collection.products limit: 8 %}.

• Pipe all dynamic output. | money for prices (raw values render cents/locale wrong), | escape for any user/merchant string (XSS), | json when emitting data into a <script>.

• Push branchy logic into metafields/metaobjects, not conditional chains. A case/if ladder over product types is data pretending to be code — bind a metafield and let Liquid do a lookup.

CLI workflow

Theme work (hot-reloads against a dev theme; never edits live unprompted):

shopify theme dev                      # local preview + hot reload
shopify theme pull                     # sync live/named theme down
shopify theme push --only templates/*  # push a subset; --ignore excludes paths
shopify theme check                    # Theme Check linter — wire into CI

Multi-environment lives in shopify.theme.toml; --environment is repeatable (shopify theme push --environment staging --environment prod).

App work:

shopify app dev      # tunnel + env + reload; provisions admin.graphql()
shopify app deploy   # release app + extensions  (NOT `app config push` — removed in 4.x)

CLI 4.x auto-upgrades via your package manager but skips CI and project-local installs — pin the version in CI so a silent bump never changes a release.

App surface — Remix + GraphQL Admin API

Apps are the Remix template. The shape:

app/shopify.server.js     # shopifyApp({ apiVersion, sessionStorage, webhooks, ... })
app/routes/app.*.jsx      # embedded admin pages (App Bridge + Polaris)
shopify.app.toml          # app config, scopes, webhook subscriptions
extensions/*              # app extensions (theme app ext, UI ext, Functions, Flow)

• Pin apiVersion in shopify.server and bump it quarterly — an unpinned client silently follows Shopify's default and can break on a version rollover.

• Use the GraphQL Admin API, not REST. REST is legacy; new fields ship to GraphQL only.

  // Bad — legacy REST Admin endpoint
  await fetch(`https://${shop}/admin/api/2026-04/orders.json`);
  
  // Good — authenticated GraphQL through the template
  const { admin } = await authenticate.admin(request);
  const res = await admin.graphql(
    `#graphql
     query Orders { orders(first: 10) { nodes { id name } } }`
  );
  

• Verify webhook HMAC before trusting any payload — authenticate.webhook(request) in the template does this; never parse a raw webhook body without it.

See references/apps-graphql.md for OAuth/session storage, mutations, App Bridge, and extensions.

GraphQL query-cost model

Admin GraphQL meters by calculated query cost (points), not request count. Every response carries extensions.cost:

{ "extensions": { "cost": {
  "requestedQueryCost": 92, "actualQueryCost": 30,
  "throttleStatus": { "maximumAvailable": 2000, "currentlyAvailable": 1970, "restoreRate": 100 }
}}}

• Over-budget returns HTTP 200 with a MAX_COST_EXCEEDED error — you must handle it in code; it is not an HTTP-level failure your client will throw on.
• Read throttleStatus and back off on restoreRate (points restored per second) rather than blindly retrying.
• Large reads use bulk operations, not paginated loops. A 10k-product export through first: pagination will throttle; bulkOperationRunQuery runs async and returns a JSONL file.

Checkout surface — the post-checkout.liquid model

checkout.liquid and additional scripts are deprecated and being removed. Dated facts:

• 2024-08-13 — Information/Shipping/Payment steps lost checkout.liquid support.
• 2025-08-28 — Plus self-migrate deadline for Thank-you & Order-status customizations (additional scripts, script tags, checkout.liquid). This was the deadline to act, not the auto-upgrade date.
• 2026-01 — automatic upgrades of Thank-you & Order-status pages begin (30-day email notice); any remaining additional-scripts / script-tag / checkout.liquid customizations stop running.
• 2026-04-15 — legacy Shopify Scripts can no longer be edited or published (existing scripts still run).
• 2026-06-30 — legacy Shopify Scripts (Script Editor discount/shipping/payment scripts) stop executing entirely.

Migrate by surface — match the old mechanism to its new seam:

Several checkout surfaces (full checkout UI customization, some Functions) are Shopify Plus-only. The full migration map, extension targets, and Functions structure are in references/checkout-extensibility.md.

App extensions catalog

• Theme app extension — your app injects an @app block / blocks into themes (no theme edit).
• Admin UI extension — surfaces inside admin pages (product, order) without leaving Shopify.
• Customer-account UI extension — extends the new customer accounts.
• Functions — discount / shipping / payment / cart logic as Wasm; the checkout.liquid logic seam.
• Flow — triggers/actions for Shopify Flow automation, exposed by your app.

Anti-patterns

Run scripts/verify.sh <theme-or-app-dir> for an advisory scan of these foot-guns.