Skip to main content

Storefront Integration Quickstart

How to CSS-customize the Marqo search widget for a new merchant using parallel agents.

What you need​

  • Store URL and Shopify admin access token
  • Storefront settings API key
  • Published theme ID (find via window.Shopify.theme in browser console)
  • Marqo theme ID (the unpublished theme with the widget installed)

Steps​

1. Backup settings​

python scripts/ecom/storefront_settings.py backup <shop>.myshopify.com --api-key "<key>"

2. Create integration doc​

Copy the template from the customization guide into docs/integrations/<shop>.md.

3. Inspect the native theme​

Navigate to the published (non-Marqo) theme in a browser:

https://<store>.com/?_ab=0&_fd=0&_sc=1&preview_theme_id=<published_theme_id>

Extract design tokens (fonts, colors, spacing) using Playwright browser_evaluate with getComputedStyle() on native product cards, filters, pagination, headings. Write findings into the integration doc's Native Theme Design Reference section.

See MSQC for an example of a completed design reference.

4. Map native filters to Marqo​

Inspect the native theme's filter facets (Brand, Color, Size, etc.) and map them to Marqo index fields. Query the Marqo index to see available document fields, then construct filter_config.value.items entries. See the filter mapping guide for details.

5. Fan out 4 CSS agents​

Spawn 4 agents in parallel using the prompt templates from the customization guide. Fill in <placeholders> with your merchant's values:

AgentWhat it styles
Product Cards + GridCards, images, title, price, badges, CTA, carousel
Filter SidebarFilter headers, options, checkboxes, toggle, mobile drawer
Pagination + Sort + CountPage buttons, sort dropdown, results count
Page Heading + LayoutHeadings, collection page, loading/error states

Each agent will independently screenshot both themes and write its CSS section.

6. Collate, inject, push​

# Combine all agent CSS outputs into one file
cat agent1.css agent2.css agent3.css agent4.css > tmp/<shop>_custom_css.css

# Inject into settings
python scripts/ecom/storefront_settings.py inject-css tmp/<shop>_backup.json tmp/<shop>_custom_css.css

# Push
python scripts/ecom/storefront_settings.py push <shop>.myshopify.com tmp/<shop>_backup_candidate.json --api-key "<key>"

7. Verify​

Open the Marqo theme preview and check:

https://<store>.com/?preview_theme_id=<marqo_theme_id>
  • Collection page: cards, filters, pagination
  • Search page: results, sort, heading
  • Mobile viewport (375px width)

8. Iterate​

Compare against native side-by-side. Fix issues, re-push. Back up final settings when done.

Reference​

  • Full customization guide -- detailed process, common CSS patterns, agent templates
  • Inline banners metafield spec -- Shopify metafield + metaobject schema for merchant-authored PLP banners (SE handoff doc)
  • MSQC integration -- first completed integration, use as reference
  • scripts/ecom/storefront_settings.py -- settings backup/push/diff/inject CLI
  • tmp/muji_ca_settings_2026-05-29T1527.json -- Muji CSS as format reference