Brand syncing

This page explains the syncing mechanic - what triggers it, what it reads, and how to make the directory match what's currently in your store.

What "syncing" actually does

A sync run does three things, in order:

1. Fetches every product from your Shopify store via the Admin GraphQL API. Pagination is automatic: works for stores with 50 products or 50,000.
2. Extracts unique vendors from the products' Vendor field. For each vendor, the app counts how many products you sell, how many have stock, and (optionally) tries to match the vendor to a collection of the same name.
3. Writes the result as a JSON blob to a shop metafield. The Brand Page theme block reads this metafield to render the storefront directory.

A sync is read-only on your products. Nothing in your catalogue is modified.

When syncs happen

Automatic sync

On every plan, the Auto-sync product changes switch in Settings (on by default) re-scans your brand list when products are added, edited, or removed, and your storefront updates on its own within a few minutes. Changes are grouped for about 5 minutes of quiet before one re-scan runs, so a big import becomes one scan instead of hundreds - at most about 30 minutes behind. When the newest scan was automatic, the Brands page shows "(auto-sync)" after the "Last scanned" date. If a sync fails, the storefront simply keeps what it had - nothing disappears - and the app retries.

Manual scan

Always available, on every plan. Click Scan now on the Brands page after any catalog change you want reflected immediately, without waiting for auto-sync.

Saving changes on the Brands page

Changes you make on the Brands page - favourites, hidden brands, collection mappings, brand logos, and brand tags - publish to the storefront automatically the moment you save. No re-scan needed. If a publish fails, a banner appears with a Re-sync to storefront button so you can retry without re-scanning.

Settings change

Saving most admin settings (sort order, accent grouping, out-of-stock visibility) writes the new config and triggers a fresh write to the metafield. You don't usually need to re-scan after a settings change.

What the scan reads

Per product:

• Vendor field. This is the source of truth. If it's empty, the product doesn't contribute to any brand.
• Total inventory. Used to detect when every product from a vendor is out of stock.
• Status. Only active products contribute to brand counts.

Per collection:

• Title and handle. Used by the brand-to-collection auto-mapper. If you have a collection called "Nike" with handle nike, the vendor "Nike" auto-maps to that collection.
• Image (if present). Used for collection-image card backgrounds when the theme block has that setting enabled.

How long a sync takes

For most stores: under a minute. For very large stores (50k+ products), the GraphQL pagination takes longer, but the scan is incremental and idempotent. You can leave the page; it runs server-side.

Only one sync runs at a time per shop. If a sync is in progress and you click Scan now again, the second click is a no-op until the first finishes. There's a 30-minute auto-expiry on the sync lock, so a crashed worker can't permanently block future syncs.

Out-of-stock detection

When every active product from a vendor has zero inventory, that vendor is marked out of stock. The Brand Page block hides out-of-stock brands by default, but you can change this in Settings with the "Out of stock brands" option (Show or Hide).

The flag refreshes every scan. So if a vendor sells out at 10am, they disappear from the storefront on the next sync (automatic or manual). When a product is restocked, they reappear on the next sync.

Hiding or removing a brand

Two different jobs, so two different controls:

• Hide a brand you still manage but don't want on the page right now. Set its Visibility to Excluded on the Brands page. It stays in your list, and the Hidden brands filter finds every one.
• Remove a vendor that isn't really a brand - a placeholder like "Default", a supplier code, a one-off name you'll never make a page for. Open the Edit menu on its row and choose Remove brand. It leaves your brand list and your storefront in one step.

Removing is reversible and nothing is deleted. The brand's logo, tags, website, and brand page content all stay exactly as they were. To bring it back, pick Removed brands from the filter button next to the search bar, then choose Restore brand from that row's Edit menu.

Two things worth knowing:

• A removed brand still counts towards your plan's brand limit, because the brand is still in your store. Removing tidies your list; it isn't a way to fit more brands under the limit.
• Removed stays removed. The next scan finds that vendor on your products again, sees that you removed it, and leaves it out. You never have to remove the same brand twice.

Forcing a fresh sync

If something looks wrong - a brand missing, a count off, a collection mapping not matching - the fix is almost always:

1. Open the Brands page in the app.
2. Click Scan now.
3. Wait for the run to complete.
4. Refresh the storefront page.

If the issue persists after a fresh scan, see the troubleshooting guide.

What syncs do not touch

• Your products.
• Your collections.
• Your theme files.
• Anything outside shop.metafields.easy_brand_page.*.

That's by design. Uninstalling the app leaves your data exactly as it was before installing, minus the metafield (which goes away after Shopify's 48-hour grace period).

What's next

• How each brand card links - collections, search URLs, and manual overrides.
• Settings that affect syncing - the toggles that re-apply on save.