> For the complete documentation index, see [llms.txt](https://docs.globo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.globo.io/swatch/help/faq-and-troubleshooting.md).

# FAQ and troubleshooting

The questions we're asked most, and what to check first.

## Start here

Three things account for most problems. Check them before anything else:

1. **Is the app embed on?** Home page → **Storefront status** should read **Live**. See [Turn on the app in your theme](/swatch/getting-started/turn-on-the-app-in-your-theme.md).
2. **Has the data been synced?** **Options → Update data**, after any change to products or variants. See [Sync product data](/swatch/getting-started/sync-product-data.md).
3. **Is your theme's own variant picker still enabled?** The app works alongside it, not instead of it.

***

## Why can't I see the swatches for my new product?

The app hasn't picked it up yet. Go to **Options** and click **Update data**. When the sync finishes, the product and its option values appear — new values arrive without a colour, so fill them in under **Set swatches**.

## Why doesn't the main product image change when I click a swatch?

Check all three of these:

* Your theme's default **Variant picker** is enabled on the product page.
* Each variant has a featured image assigned in Shopify.
* You've run **Update data** since assigning those images.

For a gallery that filters down to the selected variant's images, that's a separate feature — see [Group images by swatch](/swatch/assign-images/group-images-by-swatch.md).

## I set up image grouping and the images still don't change

Usually two systems are filtering the same gallery. Many themes ship their own *hide other variants' media after selecting a variant* setting. Go to **Online Store → Themes → Customize** and turn the theme's version off, so only the app filters the gallery.

Then confirm:

* images are assigned under **Assign images** for the option you're grouping by, and you clicked **Save**;
* product data has been synced.

## Why is the wrong variant added to the cart?

The app relies on your theme's built-in variant picker to tell Shopify which variant is selected. If that picker has been removed or hidden, the selection never reaches Shopify and the first variant is added instead.

Put the theme's variant picker back. If you now see two pickers, don't delete one — [contact us](/swatch/help/contact-support.md) and we'll hide the duplicate properly for your theme.

## My theme doesn't support app blocks. How do I show or move the swatches?

Add a container to your theme's product template — see [Themes without app blocks](/swatch/app-integrations/themes-without-app-blocks.md). Duplicate your theme before editing code.

## The app works on collection pages but not on the home page or other pages

The app renders into your theme's own product cards. It may not reach:

* blog posts and content pages;
* product lists rendered by another app;
* products inside a third-party recommendations or carousel widget.

If a particular page matters to you, [send us the URL](/swatch/help/contact-support.md) and we'll see what's possible.

## Swatches disappear after I filter or sort a collection

Filter apps rebuild the grid without reloading the page, so the swatches have to be drawn again. With **Smart Product Filter & Search** that happens automatically — there's nothing to set up, so if swatches are still missing after filtering, check the app embed is on and that collection-page swatches are turned on. See [Smart Product Filter & Search](/swatch/app-integrations/smart-product-filter-and-search.md). For other filter apps, [contact us](/swatch/help/contact-support.md).

## A product shows as sold out on a collection page but not on its product page

This happens when an option is hidden on collection pages while others stay visible — the card works out availability from the first value of the hidden option. If Pink is out of stock in S but available in M and L, hiding **Size** can mark Pink as unavailable.

Either show the option on collection pages too, or choose a different [out-of-stock treatment](/swatch/appearance/out-of-stock-styles.md).

## Two products with the same colour show different swatches

Option values are matched by their exact text. "Navy" and "navy" are two different values, each with its own swatch. Make the spelling consistent in Shopify, run **Update data**, and set the swatch once.

## Does the bundle discount work with free shipping?

Yes — the bundle discount is set up to work alongside free shipping. If a particular combination doesn't behave as you expect, [contact us](/swatch/help/contact-support.md) with the product and the discount you're testing.

## Can I change where the swatches appear on the product page?

Yes. Add the **Variant swatches** app block in the Theme Editor and drag it where you want it — see [Where swatches appear](/swatch/getting-started/where-swatches-appear.md).

## What happens if I downgrade to the Free plan?

The features that plan doesn't include stop working on your storefront: paid-only styles fall back to a basic button, and extra product groups and bundles stop showing. Nothing is deleted — your configuration comes back if you upgrade again. See [Plans and pricing](/swatch/pricing/plans-and-pricing.md).

## Still stuck?

[Contact support](/swatch/help/contact-support.md) — send a page URL, your theme name and a screenshot, and we'll take a look.