Skip to Content
DocsFAQ

FAQ

Common questions and gotchas. We add to this list as support tickets surface new patterns. If your question isn’t here, contact support .

Setup and presets

How do I switch between the 5 presets?

Open the Theme Editor → click Theme settings (gear icon at the bottom-left) → under Preset, pick one of Mercer, Warm Craft, Bold Pop, Quiet Luxe, or Tech Forward. Save. The storefront reloads with the new tokens applied.

Switching presets does not destroy your content. Your existing sections, blocks, settings, and home page composition are preserved. Switching presets only changes design tokens (colors, fonts, radius, button shape) and the signature hero on the home page.

Will switching presets lose my home page customizations?

No. Mercer uses one index.json home template across all presets, with the signature hero conditionally rendering based on the active preset. Your home page customizations — content sections, blocks, copy, settings — are preserved when you switch presets. Only the signature hero swaps.

If you’ve moved sections around, edited copy, or composed a custom home page layout, that work carries forward across every preset.

Can I mix design tokens from different presets?

No. Each preset is designed end-to-end. The colors, fonts, radius, and button shape are tuned together. We don’t recommend (or test) mixing tokens across presets. If you need a custom palette or font pair, override individual settings — the resulting look will be “the closest preset, but with X overridden”.

Can I add a 6th preset?

Not directly through the Editor. The presets are defined in the theme’s CSS tokens and JSON templates. If you want a custom preset, contact support ; we offer a preset-customization service for an additional fee.

Performance

My Lighthouse mobile score is low. Is that normal?

If you’re testing in the Theme Preview (the preview overlay you see in the Editor), yes — preview adds ~660 KB of overhead (preview-bar JS, checkout-web hooks, perf-kit, web-pixel-manager) that production storefronts don’t load. Test against the live storefront at https://your-store.myshopify.com, not the preview URL.

Live storefront benchmarks: home 99, collection 94, PDP 93 (mobile, Slow-4G throttle, 7-preset average). CLS = 0 across all preset × page combinations.

Why is my LCP image slow?

Two common causes:

  1. The image is too large. Mercer auto-generates responsive srcsets, but the source image still affects byte size. Upload images at most 2000 × 2000 px; Shopify’s CDN handles smaller variants automatically.
  2. The image is below the fold but you’ve configured it as a hero. Mercer eagerly loads the first 4 collection-card images and the hero section’s image. If your “hero” is actually a featured collection deep in the home page, it loads lazily, which delays its LCP if it ends up being the largest element.

Does Mercer support AVIF / WebP?

Yes. Shopify’s CDN auto-serves AVIF / WebP based on the visitor’s browser support. Mercer renders <img srcset="..."> with format: 'auto'; the CDN picks the best format per request.

Sections and blocks

Mercer’s header and footer are section groups with a fixed set of allowed sections (Header, Announcement, Footer, Country gate). You can add or remove sections within those groups, but you can’t add arbitrary sections to them.

If you need custom content above the header or below the footer, add a Custom Liquid section to the home page (or wherever you want it to appear) — it’ll render in the page area, between the header and footer.

Can I render a section conditionally?

Yes, with Custom Liquid. Wrap your content in a {% if %} block:

{%- if request.locale.iso_code == 'en' -%}
  <p>This shows only to English-speaking visitors.</p>
{%- endif -%}

For more conditional rendering (per-customer-tag, per-cart-total, per-product-tag), see Custom Liquid.

How do I make a section appear only on mobile (or only on desktop)?

Some Mercer sections have a Show on mobile / desktop checkbox (e.g. the Announcement section). For others, use a Custom Liquid block with CSS:

<style>
  @media (min-width: 768px) {
    .my-mobile-only-block { display: none; }
  }
</style>
 
<div class="my-mobile-only-block">
  Only renders on mobile.
</div>

Markets and B2B

How do I enable currency switching?

Set up your markets in Shopify admin → Settings → Markets with local currencies enabled. Mercer’s switcher (header, modal, or footer) automatically picks up the available markets.

My switcher doesn’t render

Check Theme settings → Markets → Switcher pattern isn’t set to Off. Then check that you have 2+ active markets in your Shopify admin. A single-market store has nothing to switch to, so no switcher renders. See Markets for the full troubleshooting list.

How do I gate B2B-only sections?

Mercer’s B2B sections (catalog badge, company switcher, tier table, quantity rules) automatically render only when customer.b2b? is true. B2C visitors see no B2B markup, no extra requests, no overhead.

For your own B2B-only content (e.g. a wholesale-specific Custom Liquid section), wrap it in:

{%- if customer and customer.b2b? -%}
  Wholesale-only content here.
{%- endif -%}

Customizing

Can I edit Mercer’s CSS directly?

You can, but we don’t recommend it. The theme’s CSS is built around a design token system. Editing the CSS directly means your changes are lost on the next theme update.

For one-off styling, use a Custom Liquid block with inline style tags. For systemic customization, override the design tokens via Theme settings → Colors / Buttons / Typography. If you need a setting that doesn’t exist, request it via support .

Can I add a new font?

The Theme Editor’s Theme settings → Typography font picker uses Shopify’s font library. Most webfonts in common use are available there. To switch to a font Mercer doesn’t ship with, just pick it from the picker. Mercer renders any Shopify font correctly.

If your brand requires a self-hosted custom font that’s not in Shopify’s library, you’ll need a custom theme modification. Contact support .

Can I add a custom homepage layout?

Yes. The home page is composed in the Theme Editor — every section is rearrangeable. If the section you need doesn’t exist, use Custom Liquid (free-form HTML / Liquid) or contact us to request a new section type.

Can I have a different header on the product page?

Not directly through the Editor — Mercer ships one header group. For per-template header variations, you’d need to fork the theme or contract a custom modification. Ask support  about per-template overrides.

Gift cards and selling plans

How do I add a gift card to my catalog?

Shopify admin → Products → Add product. Set the product type to Gift card, add denominations as variants ($25 / $50 / $100 / etc.), save. Mercer auto-detects the gift card product type and renders the recipient flow on its PDP. See Gift cards.

How do I add subscriptions?

Selling plans are managed in Shopify admin under Apps → [your subscription app] → Selling plans. Mercer renders the selling-plan picker on the PDP as a radio group below the variant picker. No merchant action required in the theme — Mercer reads product.selling_plans from Shopify.

Why can’t customers quick-add gift cards or subscription products?

Mercer gates quick-add for two product types:

  • Gift cards — the recipient flow needs a full PDP.
  • Selling-plan-required products — the subscription terms need a full PDP.

Click-through to the PDP works as expected. This gating is intentional and not configurable.

Accessibility

Is Mercer WCAG-compliant?

Mercer is built to WCAG 2.1 AA. Lighthouse a11y scores cluster at 100 / 98 / 96 across home / collection / PDP. We use native form labels, focus-visible focus rings, prefers-reduced-motion respect, SR-only skip links, and explicit id + for pairing on every input.

Full a11y is a partnership — your content matters too. Always set alt text on images, use heading levels in order, and don’t rely on color alone to convey meaning.

How do I set alt text for hero images?

Every image-picker setting in Mercer pairs with an alt-text setting in the same panel. E.g. the Image with text section has Image + Alt text side by side. Set both.

Does Mercer support reduced motion?

Yes. All animations respect prefers-reduced-motion: reduce. The header’s auto-hide-on-scroll, image hover transitions, slide-in overlays, and dot pagination auto-rotation all freeze for users who prefer reduced motion.

SEO and analytics

Does Mercer ship structured data?

Yes. PDPs render JSON-LD product schema with name, image, price, brand, availability. Article pages render JSON-LD article schema. Search engines pick these up for Rich Results.

Mercer also renders OpenGraph + Twitter Card meta on every page. Check your page source under <meta property="og:*"> to verify.

How do I add Google Analytics / Meta Pixel / TikTok Pixel?

Use Online Store → Preferences → Custom JavaScript in Shopify admin (a Shopify-side feature, not theme-specific). Or install the analytics app from the Shopify App Store; it’ll inject via Shopify’s script-tag API.

For one-off pixels, you can also use a Custom Liquid section, but admin-side preferences are cleaner.

Does Mercer support Shop Pay?

Yes. The PDP renders a Shop Pay Installments banner when eligible. The cart and checkout pages render Shopify’s accelerated checkout buttons (Shop Pay, Apple Pay, Google Pay, PayPal) per your store’s payment configuration.

Update and changelog

How often does Mercer release updates?

We aim for monthly minor releases (bug fixes + small enhancements) and quarterly major releases (new sections, preset additions, performance work). All updates are non-breaking by design — your theme settings and content always carry forward.

See Changelog for what’s shipped recently.

How do I update to a new Mercer version?

  1. From the Theme Store, you’ll see an “Update available” badge on your theme in Online Store → Themes.
  2. Click Update theme. Shopify creates a new draft theme with the update applied and your settings carried forward.
  3. Preview the draft. If everything looks right, Publish.
  4. The old theme remains in your library as a backup.

If anything is broken after the update, just publish the previous version from your library to roll back.

Support

How do I get help?

Gift card recipient flowChangelog