Muji Integration Reference

Reference doc for Muji Canada and Muji USA Shopify integrations.

Stores

Store	Shop domain	Preview domain
Muji CA	muji-canada.myshopify.com	32wvjlh081jsx6d0-48518103193.shopifypreview.com
Muji US	muji-us.myshopify.com	ve3smblf6qhk2a0s-55680663742.shopifypreview.com

Preview nonce prefixes rotate; the numeric suffix (store id) is stable. If a preview link 404s, re-fetch from Shopify admin — do not assume the prefix is still valid.

Current Themes

Marqo is LIVE on both shops as of 2026-06-18 — the published MAIN themes now ARE the Marqo themes (no separate Marqo draft to promote).

Store	Theme ID	Name	Role	Published
CA	191592300910	June 18, 2026 | MUJI CA <> Marqo - Summer Event	MAIN	2026-06-18
US	155308982462	June 18, 2026 | MUJI USA <> Marqo-Summer Event	MAIN	2026-06-18

Superseded Marqo themes (UNPUBLISHED — safe to delete after a grace period):

Store	Theme ID	Name	Created
CA	191538987374	June 16, 2026 | MUJI CA <> Marqo	2026-06-16
CA	191172313454	June 5, 2026 | MUJI CA <> Marqo	2026-06-05
US	155262976190	June 16, 2026 | MUJI USA <> Marqo	2026-06-16
US	154973798590	June 5, 2026 | MUJI USA <> Marqo	2026-06-05

Muji's pre-Marqo MAIN themes (191085216110 CA / 154901774526 US — "Muji Release v2026.06.03") are also still UNPUBLISHED. Keep them as the cleanest cutover-rollback target while Marqo is bedding in.

Marqo block settings DO NOT survive a reclone — the Summer Event reclone (2026-06-17/18) re-injected blocks but had to be reconfigured via theme editor after publish. Settings that needed manual flipping post-cutover (logged for future reclones):

• marqo-results block → "Image display order" = Model / lifestyle image first on both shops. (Without this, PLP cards render variant flat shots instead of model shots even when variantDisplayImageUrl is correctly indexed.)
• Same setting also needs flipping on marqo-featured-collection and marqo-subcollections blocks if Muji wants model-first there too. (Verified on marqo-results in this session; the other two block types share the same setting name but were not audited.)

Extension UUIDs

Auto-detected by the inject script from config/settings_data.json:

Store	UUID
CA	019e1b06-6c25-745a-81bb-abeaa6de7f31
US	019e1b06-8a4f-7852-9e7b-8a78fcd3619c

Coverage

Verified against the June 16, 2026 themes (CA 191538987374, US 155262976190) on 2026-06-17.

Muji CA

Block type	Templates	Block count
Grid (marqo-results)	63	63 (one block per template)
Subcollections (marqo-subcollections)	22	22
Featured (marqo-featured-collection)	46	190
Total templates with Marqo	131 / 142	92%

Muji US

Block type	Templates	Block count
Grid (marqo-results)	64	64
Subcollections (marqo-subcollections)	24	24
Featured (marqo-featured-collection)	46	194
Total templates with Marqo	134 / 168	79%

Coverage dropped on US relative to the May/June reclones because Muji added editorial / contextual templates (e.g. collection.*.context.international.json, collection.forest-of-verbs.json, collection.labo-preview.json, collection.muji-is-bundle.json) that the injector correctly skips. None of the new uncovered templates were ever Marqo-enabled.

Exclusions

Template	Reason	Both stores
collection.found-muji.json	Empty collection handles — would create blocks with no products	Yes
collection.tableware.json (CA only)	Editorial layout with 6+ featured-collection sections — too complex for automated injection	CA only
collection.denim-guide.json (US)	Required manual handling due to 25-section limit	US only

Uncollapse Overrides

These templates have uncollapse: true manually set on featured collection blocks (shows individual variants instead of collapsed products). State below is what's live in the June 16, 2026 Marqo themes.

CA — current (19 blocks across 6 templates)

Template	Collections
collection.aroma.json	candles, reed-diffuser, essential-oils
collection.idee.json	muji-idee, muji-idee-jasper-morrison-cutlery, muji-idee-repos-towel, muji-idee-saza-series
collection.luggage.json	hard-shell-carry-on-suitcases-32l-front-open, carry-on-36l-suitcases, check-in-75l-suitcases, check-in-105l-suitcases
collection.muji-to-go-25.json	luggage, bags, toiletry-cases, travel-containers, travel-passport-cases
collection.shelves-2.json	sus-shelving-units, pine-shelving-units
collection.stationery.json	office-storage

Discrepancy vs prior (June 5) state — re-apply may have missed flags. Verify on preview before publishing:

• collection.bedding-2025.json — previously 4 blocks (cotton-jersey-bedding, seersucker-bedding, washed-cotton-bedding, cool-touch-bedding). Now 0. Either the template was restructured upstream or the backup-driven re-apply silently skipped it.
• collection.stationery.json — previously 5 blocks. Now 1 (office-storage). Missing: pens-pencils, notebooks, markers-highlighters, desk-accessories.

If those collections still exist and render via featured blocks in the new theme, re-flag them by hand and re-push.

US — current (28 blocks across 6 templates)

Template	Collections
collection.aroma.json	candles, reed-diffusers, essential-oils, japanese-incense, relaxation-body-care
collection.bedding_2025.json	cool-touch-bedding, seersucker, washed-cotton-bedding, cotton-jersey-bedding, flannel-bedding
collection.idee.json	muji-idee-puuf-and-mini-puuf, muji-idee-jasper-morrison-cutlery, muji-idee-repos-towel, muji-idee-saza-series
collection.luggage.json	hard-shell-carry-on-suitcases-32l-front-open, hard-shell-carry-on-suitcases-36l, hard-shell-check-in-suitcases-75l, hard-shell-check-in-suitcases-105l
collection.muji-to-go-25.json	luggage, bags, travel-containers, toiletry-cases, passport-safety-cases
collection.stationery.json	pen-pencils, notebook, markers-highlighters, desk-accessories, office-storage

US re-apply landed cleanly (one delta vs prior: collection.home.json previously had an empty handle that was correctly skipped — no longer relevant).

Uncollapse state is backed up at /tmp/marqo-inject-reports/ as JSON files. When recloning a theme, the workflow re-applies these flags automatically by matching template name + collection handle. Re-apply silently skips when a template + handle pair from the backup doesn't exist in the new theme — always diff the post-reclone state against the backup.

Fallback Collection (US only)

All marqo-results grid blocks on US collection pages have:

• Fallback collection: muji-best-seller-products
• Fallback message: "These products aren't available in your region, but you might like these"

This triggers when a collection has 0 products for the current market (e.g., Argentina visitor on a US-only collection).

Verified on the June 16 US theme: 64/64 grid blocks carry the fallback. CA has no fallback by design (only one stray legacy block on outerwear from the cloned native theme — not Marqo-applied; safe to leave).

Custom CSS Notes

• Heading font: Muji's Pipeline theme uses "Roboto Condensed" for featured collection headings. Our component inherits the body font (Roboto). Set via custom CSS: .marqo-title-card-heading { font-family: "Roboto Condensed", sans-serif; }
• Header-strip alignment (added 2026-06-19): The custom_css group rule that constrains .marqo-page-heading, .marqo-collection-header, .marqo-collection-description-wrapper to max-width: 1400px; padding: 0 24px carries @media (max-width: 1024px) { padding: 0 16px } and @media (max-width: 480px) { padding: 0 12px } to match the layout's .marqo-search-layout mobile cascade. Without these breakpoints the banner + heading + description strip is misaligned with the product grid on mobile (24px header vs 12px grid → 12px overhang each side).
• 7 templates with custom CSS on native featured-collection sections (graduation-gift-guide on CA, similar on US). Flagged in reports as [HAS CUSTOM CSS] for manual review.

Empire-Native Swatch OOS Gating

Live on both shops as of 2026-06-17. The bundle reads two Empire theme settings (enable_hidden_variants_on_templates, sold_out_options) emitted as data attributes on marqo-search-embed, then gates per-product swatch OOS behavior on the indexed productTemplateSuffix:

• Cards whose suffix is in hideOOSOnTemplates → OOS swatches hidden (mirrors native Empire's apparel-template behavior).
• Cards whose suffix is NOT in the list → fall through to collectionOverrides → bundle default.

The bundle default outOfStockBehavior on US was flipped to "strikethrough" and collectionOverrides was retired (the 2-rule curated list became redundant once the template-suffix gate landed). CA still carries the legacy collectionOverrides and outOfStockBehavior default — needs verification against CA native theme behavior before mirroring the US cleanup. Tracked as a follow-up; do not propagate the US settings shape to CA without that check.

Wired by PRs #3731 (indexer), #3735 (theme extension), #3736 (bundle gate).

Display Image Fallback (PLP cards)

The indexer's variantDisplayImageUrl falls back to product.featuredImage when the per-color alt-text match misses (PR #3757). This addresses Muji products whose media library doesn't follow the "Title Color MUJI" alt convention — pre-fix, those products rendered the variant flat shot as primary on the PLP; post-fix + with image_display_order = "model-first" on the marqo-results block, the model shot renders as primary and the flat shot moves to hover.

If a product's variantImageAlt is correct but the card still shows a flat shot on a re-sync, check that the merchant theme's marqo-results block has image_display_order = "model-first" set — the indexer fix is necessary but not sufficient.

Hover-Alt Image

uiComponents.image_carousel.value.disableTag is set to "" (empty) on both shops so the hover-alt image renders for every product, not just a tagged subset. Don't add a value here unless Muji asks for per-tag suppression.

Known Issues

• Grouped block spacing: Adjacent featured collections within the same apps section have slightly different spacing than between separate sections. CSS fix uses :has() sibling selector but may need per-theme tuning.
• Title card height flash: ResizeObserver syncs title card height to product card, but there can be a brief flash at the CSS min-height before the observer fires.
• Fallback collection + prefetch: The fallback collection feature doesn't trigger on the initial page load because the loader prefetch path bypasses the fallback logic in search.ts. Tracked separately.

Resolved Issues (for context)

• Mobile banner crop (2026-06-19): .marqo-collection-image was missing height: auto, letting the HTML height="500" attr survive the cascade. The image rendered ~64% horizontally cropped by object-fit: cover. Fixed in PR #3863 (bundle). No per-shop settings change required.
• Linen Shirt PLP card (2026-06-17): rendered flat shot instead of model shot because the indexer's per-color alt-match phase produced no candidate (Muji's apparel media uses generic "Men's Linen Stand Collar Shirt" alts, not "...Natural MUJI"). Fixed via the featuredImage fallback (PR #3757) + flipping image_display_order to "model-first" on the marqo-results block.
• Subcollections rendering link title instead of collection title (2026-06-17): fixed in PR #3727.

Reclone Procedure

When Muji deploys a new theme version:

1. Backup uncollapse state from old theme:

   # Script reads all marqo-featured-collection blocks, saves those with uncollapse=true
   # Keyed by template name + collection handle
   # Output: /tmp/marqo-inject-reports/<store>_uncollapse_state.json

2. Backup admin settings:

   # Read config/settings_data.json from old theme via Asset API
   # Output: /tmp/marqo-inject-reports/<store>_settings_data_backup_<timestamp>.json

3. Compare old vs new theme:

   # List template keys from both themes
   # Report added/removed/common
   # Verify removed templates are expected (seasonal cleanup)

4. Clone the live theme in Shopify admin

5. Enable Marqo app embed on clone > Save

6. Inject:

   python3 scripts/ecom/inject_marqo_blocks.py \
     --shop <store>.myshopify.com \
     --theme-id <NEW_THEME_ID> \
     --token <TOKEN> \
     --blocks all \
     --exclude collection.found-muji.json

7. Re-apply uncollapse flags from backup

8. Re-apply fallback collection (US only) on grid blocks

9. Handle any errors (25-section limit templates) manually

10. Verify on preview before publishing

Reclone History

Date	CA theme ID	US theme ID	Trigger	Notes
2026-06-17/18	191592300910	155308982462	Muji "Summer Event" release; published as MAIN on both shops	Marqo went live on 2026-06-18. Reclone+inject pulled in Summer Event content. Block settings (e.g. image_display_order) had to be reconfigured manually post-publish.
2026-06-16	191538987374	155262976190	Muji edited live theme on 2026-06-15	Working draft prior to Summer Event cutover. Superseded but UNPUBLISHED on both stores.
2026-06-05	191172313454	154973798590	(prior baseline)	Superseded; UNPUBLISHED on both stores.
2026-05-26	—	154696974526	(US-only prior)	Superseded.