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

Three triggers, in order of priority:

Manual scan

The default for the Free plan. Click Scan now on the Brands page in the Easy Brand Page admin. Use this after any catalog change you want reflected immediately.

Scheduled scan (Premium plans)

The Premium tier adds a daily scheduled scan. The schedule page in the admin shows the next scheduled time and lets you trigger a sync manually outside the schedule.

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 toggle this in the admin Settings page ("Out of stock brands" → 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 (manual or scheduled). When a product is restocked, they reappear on the next sync.

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 Easy Brand Page admin.
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 Troubleshooting.

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 on GDPR shop/redact).

What's next

• Brand-to-collection mapping - how each brand card links somewhere.
• Settings reference - the toggles that affect sync behaviour.