---
name: "convention-shopify"
type: convention
description: Conventions for Shopify in Aled's system — store in scope, the connector-vs-theme split, product and collection naming, discounts and inventory, the ShopifyQL queries that define each KPI, and what requires human action. Read before any operation that touches the madebyneud store or its analytics. Follows the linear/github/vercel/sanity-conventions pattern; grown as the conventions solidify.
license: CC BY-NC-SA 4.0
---

# convention-shopify

How Shopify is used in Aled's system. Follows the same pattern as `linear-conventions` and `github-conventions`. This is a working draft, not the final word.

## Store in scope

| Store | Detail |
| -- | -- |
| **Made by — Neud** | `www.madebyneud.com` · `5bcb56-07.myshopify.com` · GBP · United Kingdom · plan: Shopify |

A UK homeware/ceramics brand (vintage-white tableware) at the 0→1 stage. Other stores are added here as they come online.

## The connector-vs-theme split

Two surfaces for the work a run does, kept distinct (matches the `mbn.website` project note) — and a third that neither of them reaches, below:

- **Store operations** — products, collections, orders, inventory, customers, discounts, analytics — run through the **Shopify store-management connector** (Cowork). No repo.
- **Storefront theme** — Liquid, sections, snippets, templates, assets — lives in the GitHub repo **`assoc-one/mbn-theme`** and is built by Forge, reviewed by Prism. Pixel designs and specifies it; never edits it through the connector.

Never do theme work through the connector, or store-data work through the repo.

**The third surface: Admin-only store surfaces the connector cannot reach (APP-1641).** Part of the store sits on neither side of the split above. **Shopify's marketing automations — Shopify Email and Shopify Flow — and the native popups and signup forms are Admin-UI-only: the Admin API exposes no resource for authoring them, so the store-management connector holds no tool that can stage them, at any bound.** Third-party API access to Flow exists only for an *app* contributing a custom trigger or action to the palette a merchant then builds with; it never authors a workflow from outside. The popup and signup form are theme- and Admin-configured, with no Admin API resource of their own. This is therefore neither the gated-approval shape nor a hung call: there is no approval to wait out and no call to retry. The connector is wired, authenticated and working, and the tool for this class does not exist.

**Two routes reach it, and no third.** Either the **browser-driven Admin route** already documented in this convention — an agent with a browser in the Owner's own signed-in Admin session, under the three conditions the *Human-action boundary* section states for it (APP-1213): the Owner approves the mechanism before the first write, the selection is confirmed against the intended set before the action, and the result is read back and recorded on the ticket — or the **operator doing it by hand**, recorded on the ticket as the action taken either way. One adjustment to the third condition on this surface: that paragraph reads the result back *through the connector's read path*, which does not exist here either, so the read-back is through Admin itself — the saved automation, popup or form re-read and its state recorded on the ticket. Without it, it is an unverified write to a live store, which is the point of the condition rather than the mechanism named in it. And as with the unpublish class, a ticket here is **not Blocked**: nothing upstream will ever clear it, so parking it in Blocked waits on nothing, and the class disappears only through an action on the platform, never through canon. Recorded as a reachability fact a run can look up, **once, here** — `skill-channel-ops` and `skill-lifecycle` point at this passage rather than each carrying a copy of the surface list, which is how the three drift apart. (Worked case: MBN-254, 2026-09-22 — a `skill-dispatch-run` leg on `skill-lifecycle` attempted an email-capture popup, a welcome automation and an abandoned-checkout automation through the connector, established the absence from the connector's own tool list and Shopify's dev docs, and went Blocked rather than fabricating a live flow; right about the fabrication, wrong about the state, for the reason just given. MBN-293 is the next ticket in the same shape. *Recorded as reported, not observed: the connector tool surface and the Shopify documentation behind this are APP-1641's own account and are not verifiable from a read-only refine pass without Shopify Admin access.*)

**A theme's staging preview URL is on that surface too — and it is a standing merge-leg need, not a one-off.** `mbn-theme`'s standard definition of done asks for the specimen or page to be live on the unpublished staging theme with **the preview link posted on the ticket for the Owner**, and the merge leg can confirm the first half from the repo while having no route to the second: the link is keyed to a `preview_theme_id` the Admin UI issues, and the store-management connector exposes no theme resource — products, collections, orders, customers, inventory, discounts and analytics, and nothing for themes. **Unestablished, and worth one attempt before asking:** whether the connector's general Admin GraphQL surface resolves a theme by name and yields a usable preview URL has not been tested, and a storefront password may gate the result even if the id resolves. So the standing behaviour, rather than a per-run re-derivation: try the GraphQL route once, and where it does not produce a link a reader can open, **ask the Owner for the preview URL once per merge and name why in the same comment** — the connector has no theme surface — then tick the box on their reply. Leave the box unticked meanwhile and hand off as normal; the ticket is **not Blocked**, for the reason this section already gives. Where the GraphQL route is ever proved to work, record the query here and this clause retires. (MBN-278 / PR #26, 2026-10-06 — APP-2116; distinct from APP-1345, which is the pre-merge review gap rather than post-merge link retrieval.)

## Connector writes are live-immediate

**A connector write to the storefront is public the moment it returns. There is no draft, preview or staged state on this surface (APP-1479).** The store-management connector writes product, collection and field values straight to the live store. That is the asymmetry inside the split above: theme work lands in `assoc-one/mbn-theme` and becomes public only when the theme is published, so it has a gap between written and live that review can sit inside; connector work has no such gap. Everything below follows from that one fact rather than from any judgement about how connector work should be run.

**What In Review can and cannot mean on this work type.** It can mean *the change is published and is now being checked* — post-hoc confirmation, where the reviewer's remedy is a corrective write. It cannot mean *this is held pending sign-off*, because by the time a connector ticket reaches In Review the change is already on the storefront, and a reviewer who declines it is asking for a revert rather than withholding a release. Both readings are ordinary uses of the state elsewhere in the system, which is the problem: the state name invites the gating reading and this surface cannot supply it. So a connector ticket **says on the ticket which of the two its review step is doing**, rather than leaving a reader to infer the stronger one. This is not a defect in the state and not a licence to skip review — it is what In Review means when the work type has no pre-publish state to sit in.

**Verify against the rendered page, not the field written.** A read-back that fetches the field it has just written confirms the API accepted the value, which is the thing least likely to have gone wrong. It cannot see either failure that matters: a write that took at the API without reaching the rendered page, which reads as clean; and a write that reached the page and is wrong *in context* — duplicated, contradicted, or displaced by copy already there. So the acceptance read is the **rendered page**, with the written field checked as part of that read rather than in place of it. On a live-immediate surface this is the only verification step that happens after the change is public, so it is doing the work the pre-publish gate would otherwise do. (Worked case: MBN-274 restored three care-guide lines to `info.shortdesc` across five ceramic PDPs and read that field back clean; the same three lines were already present in a separate "Care guide" accordion, so the write produced duplicate copy on the live PDP and the read-back could not have caught it. MBN-277, the PDP copy rebalance, was written live and moved to In Review in the same shape. Both surfaced 2026-09-15 in the work.Unblock session reviewing the BARA sign-off batch — APP-1479. *Recorded as reported, not observed: the MBN storefront writes and the rendered pages are not verifiable from a read-only refine pass without storefront access.*)

## Verifying theme work — what the lane has, and what it does not

A theme repo does not build and serve itself, so the claim-time instrument check (`skill-build-ticket` step 3c) has no direct translation into it and every theme ticket otherwise re-derives the substitute. Four facts settle it.

**Theme Check is a real local gate, and a missing CLI is not a missing instrument.** `shopify theme check` needs no store, no token and no network, so it runs in the delivery sandbox and a `mbn-theme` ticket's "Theme Check green" box is **met locally, not deferred to CI**. Do not test for the CLI and conclude it is absent: the base sandbox image does not carry it and an earlier leg's global install may have left it behind, so **presence is residue, not a property** — run `which shopify || npm install -g @shopify/cli` (about four seconds) and then the gate. A leg that reads `command not found` as a missing instrument hands off a PR presenting itself as unverified on a gate one command away.

**Liquid cannot be rendered locally at all.** Rendering needs the Shopify platform, so no amount of local tooling turns a theme ticket's visual criteria into a rendered page. The hosted equivalent of a Vercel preview is `shopify theme push --unpublished`, which needs store credentials the sandbox does not hold — an operator action, recorded on the ticket as the action taken, never a Blocked (nothing upstream clears it).

**The substitute for a layout or interaction criterion is a DOM-fixture harness over the committed assets** — build the DOM the snippet emits, load the repo's own CSS and JS around it in the sandbox's Chromium in the page's own cascade order, and assert geometry and behaviour. It verifies no Liquid (Theme Check and review cover that) and it is not a rendered page; what it does verify is where a theme ticket's acceptance actually lives. It has earned its keep on defects invisible to Theme Check, a diff read and every gate these repos have: an arrow buried under a `::after` pseudo-element's z-index and therefore unclickable, and a custom element silently losing its children when upgraded mid-parse.

**The fixture's container is part of the runtime, not scaffolding around it** — and this is the constraint that makes the harness honest. A hand-built container of the harness's own choosing reports geometry that is a property of the fixture, in the flattering direction, while every control still reddens correctly: controls prove the harness *can* fail, never that it is measuring the page. So derive the container from the page's own wrapper markup and CSS, assert the measured container width against the width that CSS predicts, and where the container is not derived, report only **relative** claims ("this rule is what puts them on one row") and never **absolute per-viewport** ones ("side by side at 1024"). This is `skill-review-pr`'s *Reproduce the runtime, not just the artefact* obligation stated for the theme lane, where the fixture is the only instrument available and the temptation is therefore greatest.

**The fixture's inputs are part of the runtime too — the whole stylesheet set, in load order, and the theme's own settings values.** The container rule above governs the box the fixture measures in; this governs what is poured into it, and the failure is the same shape one step earlier. A computed-style, type or colour fixture that loads a chosen subset of the page's stylesheets, or that supplies its own values for the `:root` font, scale and colour variables, is measuring a cascade the store does not have — and it fails worse than flatteringly: it can report a mismatch that does not exist on the live store and send the fix at the wrong property, while every negative control still reddens correctly. So a Shopify computed-style or layout fixture loads **the theme's actual stylesheet set in its actual load order** — every stylesheet the template pulls in, including the dev and inline overrides that load on every page of that type, not the two or three the snippet under test appears to need — and renders the theme variables from the **real theme settings values**, never invented ones. Where the stylesheet set or the settings cannot be read from the surface the run holds, the fixture is **not evidence**: the finding is written as unverified, naming which of the two could not be read. Same family as APP-1232 and APP-1341 — a fixture that does not reproduce the runtime gives confident false passes — reaching the fixture's inputs rather than its container or its loading model; the lineage is cited, not restated. (Worked case: MBN-315, `assoc-one/mbn-theme` PR #22, head `e2d3e27`, 2026-09-26 — a PDP type-parity harness loaded three stylesheets and supplied its own font variables, and its negative control reported a font-family mismatch that does not exist on the live store; the real difference was size, colour and line-height. The fix held only because it mirrored the whole declaration — a font-family-only fix would have passed that harness with the bug still on the page. *Recorded as reported, not observed, on two independent premises, neither checked against the other: (i) the font values held in `settings_data.json`, and (ii) that `devM.css`, `devS.css` and the `theme.liquid` inline heading overrides load on every PDP, and in that order. Both are APP-1793's own account; no repo and no store is readable from this cloud surface, so a flag on either premise says nothing at all about the other.* — APP-1793.)

**A catalogue or asset fact a theme criterion turns on is read through the connector, not declared unreachable.** Everything above is about what this lane can *render* and *measure*; this is about what it can *look up*, and it is a separate failure. A theme ticket's criteria routinely rest on store-side facts the repo does not hold — original image dimensions, media counts, variant data — and the delivery sandbox has no storefront, which makes "unreachable from this sandbox" the natural and wrong thing to write. It is `skill-review-pr`'s knowledge-gap rule reached from a third direction: **one blocked route is not no route** (`skill-review-pr`, the Linear-attachment paragraph; APP-364, APP-972) — the repo being the wrong route says nothing about the connector. The store-management connector's **read-only** `graphql_query` returns these facts in one call, and for image dimensions the path is `featuredMedia { ... on MediaImage { image { width height } } }`: `Image.width` and `Image.height` are the *original* pixel dimensions of the uploaded asset, not of a rendered variant. Two properties of those fields belong with the route rather than in a worked case, because a run that does not know them reads a legitimate answer as a failed call: `MediaImage.image` is `null` until the media's `status` is `READY`, and `width`/`height` are `null` for an image Shopify does not host. A null is therefore a real answer about that asset. **Verified against the live connector schema on 2026-10-05** — that is a schema read and not a store read, so it establishes that the fields exist on the connector's read path and says nothing about what any particular store returns. Where a criterion turns on such a fact, read it before judging the criterion, and treat "unreachable" as a claim to check rather than as a premise to build on. (Worked case: MBN-319 round 2 — page weight under AC 3 was judged only on rows that stopped at a newly added 1200w srcset step, with the real upload dimensions written off as unreachable after round-1 QA had asked for exactly that figure; read through the connector the originals came back at 1344, 2500 and 3× 4096, so the shipped fix fetches a 4096px original at 1920@2x and, on the every-third full-width tile, at 430@3x. *The MBN-319 figures, the PR, the head commit and the srcset rows are reported from APP-2014 and are unverified here: no repo is readable from this surface and no store read was made — only the connector's schema was checked.* — APP-2014.)

**Two Theme Check rules on locale files pull in opposite directions, so "add the missing key" is never a one-file edit.** `ValidSchemaTranslations` requires that every `t:` key a section or block references resolves to a locale entry; `MatchingTranslations` requires that every `locales/*.schema.json` file carries the same key set. Satisfying the first by adding a key to the default locale alone breaks the second across every other locale file in the theme, and the trade is heavily against it: a theme carrying twenty schema locale files turns two unresolved-key errors into nineteen parity errors, on a rule that was clean before the edit and on a different rule from the one the ticket named. So before a missing key is added anywhere, trace the offending `t:` reference to its root: a key that resolves nowhere under any name is usually a copy-paste slip pointing at an entry that was never created, and the identical block elsewhere in the theme — the same structural position in a sibling section — commonly already uses an existing key with full parity. Repointing the broken reference at that key fixes both rules with no locale-file footprint at all. Where a key genuinely is missing, it goes into **every** `locales/*.schema.json` file or into none, and an English-only scope ruling settles which *text* is written rather than how many files carry the key. (Worked case, **reported** from the filing leg and unverified here — no repo ref is readable from the authoring surface: MBN-246, `assoc-one/mbn-theme` PR #29, 2026-10-25. Two `ValidSchemaTranslations` offenses in `sections/featured-product.liquid`'s icon-with-text block pointed at `…icon_with_text.settings.content.{label,info}`, which existed under no name, while `sections/main-product.liquid`'s icon-with-text block at the identical position already used `…icon_with_text.settings.pairing_1.{label,info}`, present across all twenty schema locale files. Repointing cleared both errors and touched no locale file. The ticket carried a locked 2026-10-19 scope decision — missing keys go into the default `en` locale only — which is sound as policy and assumed a mechanism the root cause did not need: applied literally it was measured trading the 2 errors for 38 `MatchingTranslations` errors on an otherwise-clean rule. A scope decision locked before the root cause is traced carries its own premise about the required mechanism, which is `skill-ops-retro`'s authoring-side premise check read from the triage side — APP-2665.)

Wiring the harness into CI is a repo-lane question, not this convention's: it needs a browser, which is deliberately not a dependency of a theme repo, and a brand-new workflow has no pre-merge dispatch path (`convention-github`, *Pre-merge evidence for a brand-new workflow*).

## Naming

- **Products** — `Product name | Variant descriptor` (e.g. `Dinner Plate | Vintage White`). Title-case; the variant axis after the pipe.
- **Collections** — plain title-case nouns (e.g. `Tableware`, `Vintage White`). Handle follows from the title.

## Discounts and inventory

- Discounts are created via the connector; any code that spends margin is staged for the operator, not launched silently (see human-action boundary).
- Inventory is set at the location level; never zero-out or overwrite stock without confirming the location and current level first.

## KPI query definitions

So Atlas, Reach and `skill-campaign-report` all measure the same thing, each KPI maps to one canonical ShopifyQL query. Baseline captured 2026-06-19 (90-day window).

| KPI | ShopifyQL |
| -- | -- |
| Revenue | `FROM sales SHOW total_sales TIMESERIES month SINCE -365d UNTIL today` |
| Orders & AOV | `FROM sales SHOW orders, average_order_value SINCE -90d UNTIL today` |
| Sessions & conversion | `FROM sessions SHOW sessions, sessions_that_completed_checkout, conversion_rate SINCE -90d UNTIL today` |
| Repeat-customer rate | `FROM sales SHOW customers, returning_customers, returning_customer_rate SINCE -90d UNTIL today` |
| Top products | `FROM sales SHOW gross_sales, net_sales, orders GROUP BY product_title ORDER BY gross_sales DESC SINCE -90d UNTIL today` |
| Channel mix | `FROM sales SHOW orders, total_sales GROUP BY order_referrer_source SINCE -90d UNTIL today` |

Always report against the baseline and the KPI target, never as a bare number.

## Human-action boundary

The operator (not an agent) does anything that spends money, is irreversible, or is legally/financially binding: changing prices, issuing refunds, launching paid promotions, sending to a full email list, and **going live** (publishing the theme, removing password protection). Agents prepare and stage these; the operator releases them.

**The boundary reserves *going live* — and on connector work every write is that act (APP-1479).** The list above draws its line at publishing the theme and removing password protection, which are the theme surface's going-live acts, and says nothing about connector field writes. It did not need to while the two surfaces looked alike; they do not, because the connector has no separate going-live act to reserve — the write is the publish (*Connector writes are live-immediate*, above). That leaves a real question open inside this boundary's *what*, and it is **the Owner's, not canon's**: whether connector work must be **staged behind a substitute gate** — a sandbox store, a draft product, an Owner-confirmed diff before the write — or whether live-immediate writes with post-hoc review remain acceptable for this work type, given that the corrective write is itself cheap and immediate. Canon records that no such gate exists today and what In Review therefore means; it does not decide that one should. Named here so the question has a home rather than being rediscovered each time a connector ticket reaches review.

**The connector also blocks the boundary's reverse direction — a reversible *unpublish* (APP-1213).** *Recorded as reported, not observed: this comes from the filing run's own attempt and is not independently verifiable from a read-only refine pass without performing the mutation.* The store-management connector's safety policy refuses `publishableUnpublish` with `category: destructive` **regardless of the arguments passed**, and carries **no carve-out for a reversible mutation**. That is a different failure from the boundary above: there, an agent is capable and must not act; here the agent is mandated, the act is reversible, the Owner has approved it, and the tool declines anyway. Two consequences follow. **An Owner-approved unpublish is an operator hand-off, and it is neither slow nor necessarily the Owner's own clicking** — recorded on the ticket as the action taken either way. Two corrections to how this was first costed, both from performing it. **It is a bulk action, not a per-item pass:** Products → Collections → select rows → **Exclude from sales channels** → pick the channel retires the whole selection in one action (27 collections in one dialog on MBN-267); the reverse is **Include in sales channels**. The per-item shape — Sales channels section, toggle Online Store, once per collection — is what made this feel expensive enough to defer, and it is not the real cost. **And the class needs the Owner's approval, not the Owner's hands:** an agent with a browser in the Owner's own signed-in Admin session can perform the selection, the action, and the read-back verification, which is what happened on MBN-267 once the Owner approved the *mechanism*. That is a different thing from the human-action boundary proper — money, irreversibility, going live — where an agent must not act at all; here the act is reversible, the agent is mandated, and only the connector is refusing. Three conditions on the browser-driven route, and they are not optional: the Owner approves **the mechanism** before the first write, the **selection is confirmed** against the intended set before the action, and the **result is read back through the connector's read path** and recorded on the ticket. Without the read-back it is an unverified write to a live storefront. It is **not** a Blocked ticket: nothing upstream will ever clear it, so parking it in Blocked means waiting on nothing. And **the class only disappears through an action on the connector, not through canon** — adjusting its `destructive` classification so that explicitly reversible mutations are carved out of it. That is the Owner's, on the connector's own configuration surface; canon records the constraint and stops there. (Worked case: MBN-267, Owner-approved at the gate cleared 2026-09-01, whose acceptance criterion required unpublish *specifically because* it is the reversible form — "retire the 27 empty collections from the online-store channel (unpublish, not delete — reversible)" — and which moved In Progress → Blocked on 2026-09-09 with no path to clear.)

## Media and alt text — the shared-asset model

Shopify holds `altText` on the **media asset**, not on the product-image pairing. A photograph used on more than one product page is one asset with one alt value everywhere it renders, so alt text that names a specific product is false the moment the asset appears on another product's page. Two rules follow:

* **Describe the frame, never the product name.** Alt text for any asset says what is in the picture ("three stacked stoneware dinner plates, glazed rim uppermost, on a linen cloth"), not which listing it sits on. This is a structural requirement of the data model, not a style preference.
* **Count assets, not slots, before writing.** Read the media set first and identify sharing: on 2026-08-18 the store's 18 product-image slots were 13 unique assets, four of them shared across two or three product pages.

Store facts recorded, not rules: `MJCeramic010a.jpg` is held twice as byte-identical duplicate assets; the Tapas Plate's lead image is the Dinner Plate stack shot. Both are hygiene items for a merchandising pass, out of scope for an alt-text ticket. (Worked case: MBN-268, Reach, 2026-08-18 — APP-1016.)

## Gotchas

- ShopifyQL needs `FROM … SHOW …`; use `TIMESERIES` for trends, `GROUP BY` for cuts.
- `total_sales` is net of discounts and returns; `gross_sales` is not — be explicit which a report uses.
- For resources without a built-in connector tool (metafields, pages, markets, gift cards), use the GraphQL Admin API tools rather than reporting the data as unavailable.
- `validate_graphql_codeblocks` documents its parameter as `code_blocks`/`code`, but the schema wants `codeblocks[].content` — two failed calls before it takes if you trust the description (APP-1016).
- **`SEOInput` on `productUpdate` is full-replace, not a patch — an omitted field in a composite input is an explicit clear, not "leave unchanged" (APP-2410).** Passing `seo: {title: "…"}` alone sets `seo.description` to null, returns a clean 200 with no `userErrors`, and the mutation's own response echoes the null — so the write looks successful and the echo reads as a report of prior state rather than as the damage it just did. **Read the product's current `seo { title description }` first and pass both fields on every `productUpdate` that touches either**, then re-read with a fresh `products` query rather than trusting the mutation response: the mutation echo is the write's own account of itself, which the *Verify against the rendered page, not the field written* rule in *Connector writes are live-immediate* above already rules out as acceptance evidence. **Scope, stated honestly rather than over-generalised:** this is verified on `SEOInput` only — whether Shopify's other composite input objects share the shape is untested — so **treat an unread composite input as full-replace until shown otherwise**, rather than assuming either way. **The family:** this is the same full-replace class `convention-linear` records for Linear's own `labels` and `patch` params, now reached on a second connector, which is what makes it a class rather than one connector's quirk. (Worked case: five live ceramic SKUs had their `seo.description` silently nulled by a title-only write and then restored by re-issuing each `productUpdate` with both fields, caught only because that ticket's definition of done required a fresh GraphQL re-read of `seo { title description }` rather than the write response — MBN-333, 2026-10-17. *Recorded as reported, not observed: no `productUpdate` was issued and no store was read from this surface, so the five SKUs, the null echo, the original descriptions and the restoration are APP-2410's own account, and whether the restored strings match the originals verbatim is unverified here too. The rule does not rest on that account: it rests on the reported symptom and on the defensive discipline — read both, write both, re-read through a separate query — which is correct whether or not the composite behaves as reported.*)
