How to Build a Shopify Store With Claude Code

What Claude Code can and cannot do here

Shopify is a hosted platform, which changes the shape of the work. You are not building a web application; you are building a theme that runs inside someone else's rendering pipeline, plus a catalogue of data that lives in someone else's database. Both are reachable programmatically, and both have limits worth knowing before you start.

What works well. Theme code is just files — Liquid templates, CSS, JavaScript, JSON — in a directory that Claude Code can read, edit, and push. That part behaves like any other codebase and benefits from the same workflow. Store data — products, variants, pages, policies, navigation, redirects, metafields — is reachable through the Admin API, so creating a product or fixing thirty page titles is scriptable rather than a click-through.

What does not. Checkout is not yours. On most plans you cannot edit it, and even where you can the surface is deliberately narrow. Payment configuration, tax settings, shipping profiles, domain verification, and app installation are admin-only, often deliberately, and no amount of API access changes that.

What needs care. A theme push affects a live storefront. An Admin API mutation changes real data. There is no local database to reset — the development store is a store. This is the main way an otherwise ordinary session becomes an incident, and most of the safety practice below exists because of it.

Two ways in: the CLI and the Admin API

There are two distinct access paths and they solve different problems. Using the wrong one is a common source of friction.

In practice you want both. The CLI for the theme development loop, where its hot reload and preview are genuinely useful; the Admin API for everything that is data rather than code, and for anything you want to script or verify repeatedly.

The Admin API's GraphQL endpoint is the current one — the REST Admin API is legacy. Ask for GraphQL explicitly, because there is a great deal of older REST example code in the world and a session left to its own devices may well reach for it.

Use the Shopify Admin GraphQL API, not REST. Pin the API version
explicitly in the URL rather than relying on a default.

Every mutation response includes a userErrors field. Check it. A
GraphQL request can return HTTP 200 with a populated userErrors
array and no change made — treating 200 as success is a bug.

Handle throttling: the API is cost-based, and the response includes
the query cost and remaining budget. On a throttled response, back
off and retry rather than failing.

That last paragraph is worth setting up once. Shopify's GraphQL rate limiting is calculated on query cost rather than request count, and the response tells you what you have left — which means a well-written client can pace itself instead of guessing.

Setting up safely

Before any of the interesting work, three decisions that determine whether a mistake is recoverable.

Develop against a theme that is not live

Shopify themes have roles. Exactly one is MAIN — the live storefront. Everything else is unpublished. All development happens against an unpublished theme, and publishing is a separate, deliberate act.

This is important enough to enforce mechanically rather than remember. Whatever push mechanism you use, make it refuse the live theme unless something explicit overrides it:

if theme["role"] == "MAIN" and os.environ.get("ALLOW_LIVE") != "1":
    sys.exit("Refusing to push to the live theme.")

Five lines. It converts "I hope nobody passes the wrong theme ID" into a thing that cannot happen by accident. I would not run a theme workflow without it.

Keep the theme in version control

Shopify keeps a limited number of themes and its own history is not a substitute for git. Pull the theme into a repository first, commit, and work from there. The repository is the source of truth; the store is a deployment target.

Take a backup before the first push

Duplicate the live theme in the admin before you touch anything. It costs one click and it is the difference between "revert the commit and push" and "rebuild from memory".

Credentials without leaking them

An Admin API token can read customer data and change your catalogue. Treat it accordingly, and be aware that a coding agent introduces a specific new way to leak one: it will happily write a working script that hard-codes the token, because that is the shortest path to the thing you asked for.

Say otherwise, explicitly:

Credentials are in [PATH], which is outside this repository and
gitignored.

Read them at runtime from that path or from the environment. Never
hard-code a credential. Never write one into a file in this
repository. Never write one into a theme file — everything under the
theme directory is publicly served. Never print one in full; redact
it in any diagnostic output. Never include one in a commit.

If you need to show me a request for debugging, redact the
authorisation header.

Two Shopify-specific consequences worth stating separately.

Theme files are public. Anything in a theme's assets, snippets, sections, or templates is served to browsers. A token in a Liquid file is not merely committed, it is published. This is a different and worse failure than the usual one.

Token caching needs a home outside the repo. If you use a credential flow that mints short-lived access tokens, they need to be cached somewhere or you will mint a new one per request. Put the cache outside the repository — under ~/.cache/ — with restrictive file permissions. A gitignored file inside the repo is one git add -f from being public.

Finally, scope narrowly. A custom app's access scopes are chosen when you configure it, and a token limited to what you actually need is a much smaller problem if it escapes. If a task fails with a permission error, the correct response is to consider whether it should be permitted, not to reflexively widen the scope.

The theme architecture Claude needs to know

Shopify themes have a specific structure, and a session that does not know it will produce code that looks right and does not render. Worth stating up front:

layout/          Wraps everything. theme.liquid is the default.
templates/       One per page type. JSON files list which sections
                 render; .liquid files contain markup directly.
sections/        Modular, reorderable blocks. Configurable through
                 a {% schema %} block at the bottom of the file.
snippets/        Reusable fragments, included with {% render %}.
assets/          CSS, JS, images. Publicly served.
config/          settings_schema.json defines theme settings;
                 settings_data.json holds their values.
locales/         Translations.

Four things about this are non-obvious enough to be worth telling a session directly.

JSON templates can choose their layout. A template can specify "layout": "landing" to render inside layout/landing.liquid instead of the default. This is how you give one page type entirely different chrome without touching the rest of the theme, and it is much cleaner than conditionals inside the main layout.

Section schemas define the settings. The {% schema %} block at the bottom of a section is what produces its controls in the theme editor. Settings have types, and the type determines what a valid value looks like — which matters more than it sounds, as the gotchas section explains.

Section groups are JSON. Headers and footers are typically section groups: JSON files listing which sections appear and in what order. They reference sections by filename, which creates an ordering dependency at push time.

{% render %}, not {% include %}. The older include tag is deprecated and has different, worse scoping behaviour. Say so, because plenty of older examples still use it.

A CLAUDE.md for a theme project

Put all of the above where it does not have to be repeated. A theme project's CLAUDE.md has a distinctive shape because the prohibitions are unusually load-bearing:

# CLAUDE.md

## Project
Shopify theme for a one-product store. Source of truth is
theme/dev/. The store is live and taking orders.

## Commands
- `scripts/theme_pull.py` — pull the theme from the store
- `scripts/theme_push.py` — push to the development theme
- `shopify theme check` — lint Liquid
- `tests/run-all.sh` — full local check

## Do not
- Never push to the live theme. Push to development and preview.
- Never put a credential in any file under theme/ — theme files are
  publicly served.
- Never use {% include %}. Use {% render %}.
- Never hard-code a colour, spacing, or font value that exists as a
  CSS custom property.
- Never replace the generated sitemap. Shopify maintains it.
- Never add review or rating structured data. We have no reviews.
- Never edit the vendor theme's own files. Additions go in
  sbs-prefixed files so they survive a vendor update.

## Conventions
- Our sections and snippets are prefixed `sbs-`
- All CSS in assets/sbs.css, all JS in assets/sbs.js
- Design tokens are CSS custom properties on :root

## Before finishing
1. `shopify theme check` — zero offences in our files
2. Push to development and fetch the affected preview URLs
3. Report the actual status codes, not "should work"

## Gotchas
- Push order: .liquid assets, layouts, snippets and sections must
  land before section-group JSON that references them.
- `policy` is not a template type. See docs/STORE-ARCHITECTURE.md.
- Theme setting values must match their schema type. An empty
  product_list is [], not "".

The "never edit the vendor theme's own files" rule is worth adopting even if you never update the theme. Prefixing everything you add means the diff between your work and the vendor's is always obvious, which makes an update survivable and makes it clear which offences from the linter are yours to fix.

The development loop

The loop that works:

1. Edit files locally in the repository
2. Lint with shopify theme check
3. Push to the development theme
4. Fetch the preview URL and check the actual response
5. Commit
6. Publish only when a batch of work is verified

Step four is the one that gets skipped and the one that matters. Liquid fails softly: a broken tag frequently renders as empty output or as visible text rather than an error, so a push can succeed while the page is wrong. "The push returned success" is not evidence that anything works.

Make the check explicit in the instruction:

After pushing, fetch the preview URL for each affected page and
confirm: HTTP 200; the expected content is present in the response
body; no Liquid error text appears in the output; no template
placeholder rendered literally.

Report the actual status codes and the specific strings you found.
Do not report success on the basis of the push result.

One further note on theme check. On a vendor theme it will report offences in files you did not write and should not touch. Filter to your own files and hold those at zero — a linter whose output you have learned to skim is not doing anything for you. It is worth deliberately introducing an error once to confirm your filtering actually catches things; a clean report from a broken filter looks identical to a clean report.

Building the storefront

With the safety and workflow in place, the actual construction. A few things specific to doing this on Shopify with an agent.

Work section by section

Sections are the natural unit — self-contained, individually previewable, individually revertible. Build one, verify it renders, commit, move on. A session asked to build an entire page in one pass produces a diff you cannot check against a live storefront in any meaningful way.

Give the theme editor real controls

A section with hard-coded copy is a section that requires a developer to change a headline. Put text, images, and links in the schema:

Build this as a section with a schema, so everything editable is
editable in the theme editor: heading, body, button label, button
link, and image.

Give every setting a sensible default so the section renders
correctly the moment it is added, before anyone configures it.

Use setting types that match the data — url for links, image_picker
for images, richtext where formatting is wanted. Do not use text for
something that should be a URL.

"Renders correctly before anyone configures it" prevents a specific annoyance: a section that appears completely broken in the editor until you fill in six fields.

Keep styling on tokens, including Shopify's own elements

Some elements come from Shopify rather than from you — the add-to-cart button in some contexts, form controls, checkout-adjacent UI. These carry the vendor theme's styling, which will not match yours and may not meet your contrast standard. Styling them onto your tokens is legitimate and usually necessary; on this build, the default add-to-cart button measured 3.59:1 against its background, below the 4.5:1 required for text.

Creating the product

Products are data, so this is Admin API work rather than theme work. A product has fields that are easy to set and easy to forget, and several of them are only discovered as wrong when a customer hits them.

Create the product via the Admin GraphQL API.

Set: title, descriptionHtml, product type, vendor, tags, handle,
SEO title and description, and the variant price.

Then verify by reading it back and confirming each field.

Check specifically:
- The handle is what we intended, not an auto-generated variant
- It is published to the sales channels we need
- The variant's requiresShipping flag is correct
- The status is what we expect

Report what the API actually returned, not what you sent.

"Report what the API returned, not what you sent" catches partial successes, which are the awkward case: a mutation that succeeds while silently ignoring one field is indistinguishable from a full success unless you read it back.

Two fields matter more than their prominence suggests. The handle becomes the product URL, and changing it later means a redirect and a period of split search signals — get it right the first time. Publication to sales channels is separate from the product's status: a product can be "active" and invisible on your storefront because it is not published to the online store.

Digital products and delivery

If you are selling a file, this section is the one that decides whether the business works.

Two things must be true.

The variant must not require shipping. Otherwise checkout asks for a shipping address and may attempt to calculate rates for a download. This is a single boolean and it is easy to leave at its default.

Something must actually deliver the file. Shopify's core product does not do digital delivery. It is handled by an app — Shopify's own free digital downloads app or a third-party equivalent — which attaches a file to the variant and issues a download link on order completion.

That second point deserves emphasis because of the failure mode. Everything else can be correct — the product live, the price right, the checkout working, the payment captured — and the customer receives nothing. There is no error. The order looks successful from every angle except the customer's.

App installation is admin-only, so this is a step an agent cannot complete for you. What it can do is verify it:

Verify digital delivery is configured for this product.

Check: which apps are installed on this store; whether a digital
delivery app is among them; whether a file is attached to the
product or its variant; and whether requiresShipping is false on
the variant.

If any of these is not satisfied, say so plainly. This is the
difference between a customer receiving the product and paying for
nothing.

Run that check before the store accepts its first order, not after. And place a real test order end to end — pay, receive the email, click the link, open the file. Every intermediate step can be correct while the last one fails.

One related note on where files live. It is tempting to upload the product file through the Files API and link to its CDN URL. Do not: files uploaded that way are publicly accessible to anyone with the URL, which bypasses checkout entirely. Paid files belong in the delivery app, which gates access behind an order.

Policies and legal pages

Shopify has built-in policy documents — refund, privacy, terms of service, shipping, contact information — that live at /policies/<handle> and are managed as store data rather than as pages. They are also linked automatically from checkout, which is why using the built-ins matters rather than creating ordinary pages with the same names.

Both are settable through the Admin API, so this is scriptable. Two things to watch.

Digital goods change what the policies must say. A refund policy written for physical returns is wrong for a download, and a shipping policy on a store that ships nothing should say so explicitly rather than being absent. Consumer law in several jurisdictions treats digital goods specifically — including how a right to cancel interacts with immediate access to a download — so this is a place to write what is actually true about your product and take advice if the stakes warrant it, not to accept a generated template.

If you previously had pages at other URLs, redirect them. A store that once had /pages/privacy and now has /policies/privacy-policy needs a redirect, or the old URL 404s for anyone who bookmarked or linked it. URL redirects are Admin API data and take a moment to create in bulk.

Structured data without lying

Product structured data is worth having; it is also the easiest place on a store to publish something false without noticing.

Add Product structured data to the product template.

Use values from the actual Liquid objects — never hard-code a price,
availability, or currency.

Include: name, description, image, sku if present, brand, and an
offer with price, priceCurrency, availability, and url.

Do NOT include aggregateRating or review. We have no reviews.
Marking up reviews that do not exist is a policy violation and can
result in a manual action.

Validate the output against Google's Rich Results Test and report
the result.

The review prohibition is not hypothetical. Fake review markup is one of the more reliably penalised structured data abuses, and a helpful session generating a "5.0 from 127 reviews" placeholder for a store with no reviews is an entirely plausible accident.

The other rule — values from Liquid objects, never hard-coded — is what keeps the markup true after the first price change. Hard-coded structured data is correct exactly once.

Accessibility on a Shopify theme

Themes bring their own accessibility baseline, and it varies. Assume nothing and check.

The areas that most often fail on a commercial theme: colour contrast in buttons and on promotional backgrounds; focus states removed for aesthetic reasons; carousels and slideshows that are not keyboard operable; mobile menus that trap focus or fail to return it; form fields labelled with placeholders; and quantity selectors built from unlabelled buttons.

Two things make an audit here worth trusting.

Audit the rendered page, not the source. Liquid means the source is not the output. Contrast in particular has to be computed against the backdrop that actually renders, and a specificity conflict between two stylesheets can produce text the same colour as its background while both files look entirely correct in isolation. On this build a primary call-to-action rendered at 1:1 contrast — invisible — because a generic link rule outranked the button rule by a single point of specificity. Nothing in the source suggested it.

Test the states that only exist after interaction. An open mobile menu, a focused field, an expanded accordion, an error state. Static analysis sees none of these.

Audit the rendered storefront for accessibility, not the Liquid
source.

Load each key page in a real browser at 320px and 1280px. For each:
compute contrast for every text and background pair from computed
styles; check every interactive element is keyboard reachable with a
visible focus indicator; verify form controls have programmatically
associated labels via label[for], aria-label, or aria-labelledby;
check heading order; check for horizontal overflow.

Then open the mobile menu and re-check focus behaviour.

Report measured ratios. Do not assert compliance without numbers.

Store data beyond products

Several things that feel like theme work are actually store data, which means they are Admin API work and are scriptable. Knowing which is which saves a lot of searching through Liquid for something that was never there.

Navigation menus are data. The theme renders whatever menu handle it is pointed at; the menu's contents live in the store. This is why editing the theme never changes the header links, and why building the navigation is an API call rather than a template edit.

URL redirects are data, and bulk-creatable. Any time you change a handle, move a page, or consolidate URLs, the redirect is one mutation. Worth building into the same script as the change itself, so the two cannot get separated.

Metafields are custom fields on products, collections, pages, and the shop itself. They are the right answer whenever you find yourself wanting to encode structured information — a specification table, a file version, a release date — that has no native field. Define them with a type, and the theme can render them safely:

Define a metafield definition on the product with an explicit type
and a clear namespace and key, then set its value on our product.

In the theme, render it defensively: check the metafield exists
before rendering the block that displays it, so a product without
the value renders nothing rather than an empty heading.

Confirm by reading the product back and by fetching the rendered
page.

The defensive rendering note matters because metafields are per-record. A section that assumes the value exists renders a stray label on every product that lacks it.

Performance: what you actually control

You do not control Shopify's infrastructure, and you do not need to — it is fast. What you control is what the theme loads, and that is where storefront performance is usually lost.

Four things account for most of it.

Apps. Every installed app can inject script into the storefront, and they rarely remove it cleanly when uninstalled. An app added for a two-week experiment eighteen months ago may still be loading on every page. Audit what is actually being requested rather than what you believe is installed.

Images. Shopify's CDN will resize on request, so an image should be requested at the size it renders, with a responsive srcset, explicit width and height to prevent layout shift, and lazy loading below the fold. A theme that requests one large image and lets CSS shrink it is the most common single cause of a slow product page.

Fonts. Shopify's font picker handles loading sensibly. A custom font added by hand often does not — check for a render-blocking stylesheet and an unnecessary weight or two.

Your own JavaScript. Defer it. Almost nothing in a storefront needs to block rendering.

Audit this storefront's loaded resources on the home and product
pages.

Report the actual bytes: JavaScript by origin, CSS, images with the
largest named individually, and fonts. Identify every third-party
origin contacted and which app it belongs to. Identify the LCP
element and every render-blocking resource.

Flag images requested larger than they render, and any script
loading on every page for a feature used on one.

Measure it — do not estimate. Do not change anything yet.

Then act on it in order of bytes saved, and re-measure. Note that removing an app's script tag from the theme is not the same as uninstalling the app, and an app you still use may legitimately need its script — the trade-off is yours, not the agent's.

SEO: what Shopify does for you

Shopify handles several things automatically, and knowing which ones prevents a well-meaning session from breaking them.

The sitemap is generated and maintained. Shopify produces /sitemap.xml as an index pointing to child sitemaps for products, collections, pages, and blogs, and updates it as content changes. Do not replace it with a hand-written file. A static sitemap is correct on the day it is written and wrong thereafter. The right action is to validate it — fetch it, fetch the children, and confirm your important URLs are present and return 200.

Canonical tags are emitted by the theme's canonical_url object. Check they are correct rather than adding your own.

/robots.txt is generated with defaults that block the cart, checkout, and various internal paths. It is customisable through a template, but the default is sensible and changing it is a good way to deindex yourself. Verify it does not block anything you want crawled, then leave it alone.

What is genuinely yours: page titles and meta descriptions, heading structure, internal linking, image alt text, content quality, and structured data. That is where the work should go.

One theme-level detail that is easy to miss: if your layout builds the <title> from a theme setting that has never been filled in, it may fall back to the .myshopify.com domain. That is a real title tag on a real indexed homepage, and nobody notices because the page looks fine. Fetch the homepage and read the actual title.

The SEO workflow guide covers the rest of this ground in detail.

Agent discovery: agents.md and llms.txt

A newer consideration, and one worth a few minutes because it is cheap and few stores have done it. AI assistants and agents increasingly fetch a machine-readable description of a site rather than parsing its HTML, and Shopify supports serving one from the theme.

A single theme template can back all three of the conventional discovery URLs — /agents.md, and as a fallback /llms.txt and /llms-full.txt. What belongs in it is a plain-Markdown summary: what the store sells, the key URLs, the policies, and how to buy.

The one thing that catches people is that this template renders in a restricted Liquid context. Most global objects are unavailable — there is no collections, no pages, no settings. You get the request object and an agents object exposing store-level values like the store name, URL, currency, and sitemap URL. Anything else renders empty, silently, and the file looks fine locally because you were reading the source rather than the output.

Create the agents.md template for this theme.

It renders in a restricted context: only the `request` and `agents`
objects are available. Do not reference collections, pages, settings,
or any other global — they render empty with no error.

Use the agents object for store name, URL, currency, and sitemap.
Hard-code the specific page paths, since no object exposes them.

Output plain Markdown, no HTML. Then fetch /agents.md, /llms.txt,
and /llms-full.txt on the live domain and show me the actual bodies
returned.

The final instruction is the whole test. Because failures here are silent, reading the rendered output is the only way to know whether half your template evaluated to nothing.

QA before you take money

A storefront has a specific failure that ordinary sites do not: it can look perfect and take payments without delivering anything. QA accordingly.

That last row is unusual and worth explaining. If your storefront makes specific claims — a page count, a file count, a number of templates — those are checkable assertions about a real artefact, and they drift as the product changes. Verifying them mechanically is a short script and it prevents shipping a page that overstates what the customer receives:

Extract every numeric claim from the storefront copy — counts,
sizes, quantities, durations.

For each, find what the actual value is in the product bundle and
compare. Report every claim with its stated value, its actual value,
and whether they match.

Any mismatch is a defect. An overstatement is worse than an
understatement, but flag both.

Going live

The order matters, because each step is easier to fix while nobody is watching.

1. Publish the theme. Development theme verified, then publish. Keep the previous theme; it is your rollback.
2. Verify the live storefront. Re-run the crawl against the real domain. Different theme role, different URLs, occasionally different behaviour.
3. Confirm delivery. Before the password comes off. This is the last moment it is free to be wrong.
4. Place a real order. With the password still on if your setup allows it. Complete payment, receive the file, then refund yourself.
5. Remove the storefront password. The store is now public.
6. Verify the domain. Both apex and www resolve, HTTPS works, one canonically redirects to the other.
7. Check the sitemap and robots.txt on the live domain.
8. Submit to Search Console — after verifying ownership, and only if you intend to manage it.
9. Watch the first real orders. Manually confirm the first few customers actually received the product.

Step nine is not optional. Automated verification tells you the mechanism worked in the case you tested. The first genuine customer is the case you did not test.

Gotchas that cost real time

These are from building this store, not from documentation.

Policy pages are not a template type

If you want policy pages styled differently, the obvious approach is a templates/policy.json. Shopify rejects it with an explicit error: template type policy does not support JSON templates. The natural next move is templates/policy.liquid — which uploads successfully and is then silently ignored, because policy is not a template type at all. You get a successful push and an unchanged page, which reads exactly like a caching problem and is not one. The working approach is to branch inside the layout on the page type.

Push order matters

Section-group JSON files reference sections by filename. Push the JSON before the section file exists and the push fails on an unknown section. Order: assets, layouts, snippets, and sections first; then section-group JSON; then templates; then configuration. Worth encoding in your push script rather than rediscovering.

Theme setting values must match their schema type

Writing settings_data.json programmatically, it is natural to clear a setting by writing an empty string. Shopify rejects this for typed settings — a product_list expects an array, and "" is an error, not an empty value. The push fails with a message about the setting rather than about the type, which sends you looking in the wrong place. Map each setting to its schema type's correct empty value.

Missing vendor snippets throw Liquid errors

Some commercial themes reference snippets that ship conditionally. If one is absent, {% render %} produces a visible Liquid error on the page. An empty stub file with the expected name fixes it without touching vendor code.

Fragment links break on every page but one

A call-to-action linking to #buy works on the page containing that element and silently does nothing everywhere else — no error, no navigation, just a click with no effect. Root-relative links (/#buy) work from anywhere. This is easy to miss because it works perfectly on the page you were building.

The default theme's contrast may not meet AA

Commercial themes are designed to look good in a screenshot. Measure rather than assume, including on elements Shopify renders rather than your theme.

Liquid fails quietly

The recurring theme in all of the above. A broken tag renders as nothing or as visible text; a wrong object renders as empty; an ignored template renders the previous version. The push succeeds either way. This is why "fetch the URL and check the response body" belongs in your finishing procedure rather than in your intentions.

Where to go next

The general workflow this sits inside is in how to build a website with Claude Code. The prompts here are Shopify-specific applications of the patterns in the prompt library, and the theme CLAUDE.md above is a specialised version of the structure in creating a production CLAUDE.md. Once the store is live, the SEO optimisation workflow covers making it findable.

Sources and further reading

• Shopify: theme architecture — layouts, templates, sections, section groups
• Shopify: Admin GraphQL API — the current Admin API
• Shopify: API rate limits — cost-based throttling
• Shopify CLI for themes
• Google: product structured data
• W3C: WCAG 2.2