Product Page Automation

DECISION 1Which variants exist

One skeleton, five production types. They differ only in flags, stock location and size filtering — which is why this is a rule table and not five code paths that drift apart. Change the type and watch the variant set recompute.

The type names are reconstructed; the four behaviour columns are the specified part.

Only sizes with stock at either warehouse become variants, and real per-warehouse quantities are written.

VARIANT SET FOR MRD-2207 / DEEP TEAL · 4 VARIANTS · 129.00 EACH

• S excluded — no stock at either warehouse

DECISION 2Where the quantity lands

The mutation is sent, and the storefront hands back its variants in its own order — and here it did not hand back size M at all. The tool now has to put each quantity on the right variant.

The rule the system runs on: every quantity is looked up by SKU, so the storefront's ordering cannot matter.

WHAT WAS WRITTEN

1. SIZE XS12 units — intended for size XS (MRD2207-DTL-XS)correct
2. SIZE L7 units — intended for size L (MRD2207-DTL-L)correct
3. SIZE XL3 units — intended for size XL (MRD2207-DTL-XL)correct

SKIPPED WITH A NOTE · storefront returned no variant for MRD2207-DTL-M — 40 units not written, logged and skipped

Every quantity landed on its own size. A variant the storefront did not return is skipped with a note rather than having its quantity handed to whichever variant happened to be next.

DECISION 3Create, update, or leave alone

A lookup sheet is consulted before anything is written. No row means create, as a draft. A row hands back the product id. A row the snapshot calls live is skipped rather than quietly rewritten — which matters a great deal, given what an update re-sends.

In the specification this page rebuilds, the lookup is a snapshot refreshed by its own hourly job. MRD-3110 / EMBER went live 47 minutes ago and the snapshot still says draft, so the run would rewrite a page customers are currently looking at. That window was up to an hour wide, and it is written into the caveat register rather than left to be discovered. Since September 2026 production also updates the lookup per product by webhook within seconds, with a full snapshot each night catching any delivery that is missed.

THE SHARP EDGEAn update re-sends the whole page

A page is a deterministic function of the sheets. That is the point of the tool and it is also its cost: an update re-sends handle, SEO, description, tags and images, so a correction made anywhere other than the sheet does not survive the next run. Six hand edits are sitting in the storefront admin below.

6 of 6 fields would be replaced by this run. Press it and watch a merchandiser’s afternoon disappear.

THE REGISTERKnown caveats, written down

The production README carries a register of sixteen known caveats. Requiring it be written down rather than remembered was a decision, and it is the most useful artefact the project has.

That file is not in this repository, so this is not a transcript of it. These 14 are the register this rebuild can stand behind — 9 of them demonstrated on this page, the rest following from the specification it was written from or, for the nightly snapshot, from the production repository’s own deploy files. Claiming sixteen and showing an approximation would be the exact failure the register exists to prevent.

1. 01An update re-sends handle, SEO title, SEO description, description, tags and images. A hand edit made in the storefront admin is overwritten on the next run.SHOWN HERE
2. 02The create-or-update lookup is a snapshot. A page can go draft → active between refreshes, and the run will not know.SHOWN HERE
3. 03Inventory is matched to a variant by SKU. Position-matching a quantity list against the order the storefront returned once put quantity on the wrong size.SHOWN HERE
4. 04A variant the storefront does not return is skipped with a note. The quantity is not written, and the run says so.SHOWN HERE
5. 05A style with zero stock at every warehouse is skipped with a message, not created as an empty page.SHOWN HERE
6. 06Under the placeholder types every quantity is identical, so a mis-assignment is indistinguishable from a correct one until real quantities differ.SHOWN HERE
7. 07Creation always writes a draft. Nothing in the tool publishes a page.SHOWN HERE
8. 08A size with no row in the UPC list gets no variant, because a variant with no SKU cannot be matched on the next run.SHOWN HERE
9. 09A page the snapshot calls live is skipped rather than rewritten — which also means a genuine correction to a live page cannot be pushed by this tool.SHOWN HERE
10. 10The six upstream sources are read once and cached for the life of the run, so a sheet edited mid-run is not picked up.STATED ONLY
11. 11Images are attached by their existing storefront file identifier, so a file that has been deleted or replaced upstream will not re-upload itself.STATED ONLY
12. 12The resume ledger must live on a mounted volume. On a container's ephemeral filesystem the resume state dies with the container.STATED ONLY
13. 13The full snapshot runs once a night, not when the container starts, so a webhook delivery Shopify has given up on stays missing from the lookup until the next nightly run.STATED ONLY
14. 14A Sheets values:append that returns 5xx after the server applied it cannot be blind-retried — there is no idempotency token, and a retry duplicates the row.STATED ONLY