Product Sync

HF Product Manager works with a local cache of your product data. Sync is the process of downloading product information from Shopify into this local cache so you can work with it instantly -- searching, filtering, sorting, and editing without waiting for API calls.

What Sync Downloads

A full sync downloads your entire Shopify catalog into the local cache:

Products -- titles, descriptions, handles, status, vendor, type, tags, SEO fields, category, template
Variants -- prices, SKUs, barcodes, weight, inventory policy, option values, compare-at prices
Images -- URLs, alt text, position (thumbnails are cached locally for fast grid display)
Metafields -- all product and variant metafields with their types and definitions
Collections -- collection memberships for each product (manual and smart collections)
Publications -- which sales channels each product is published to

All of this data is stored in a local SQLite database per store, so subsequent launches load instantly from cache.

The Sync dropdown in the toolbar provides these options:

Option	Description
Sync Now	Runs a quick sync (delta) -- only downloads changes since the last sync
Full Sync	Downloads all products from Shopify, replacing the local cache
Refresh Inventory	Re-downloads inventory levels for all variants
Sync Sales Data	Downloads order/sales data from Shopify for use in reports
Clear Cache	Deletes all cached products for the current store (next sync will be a full download)

You can also Resync from Shopify for specific products by selecting them in the grid, right-clicking, and choosing Resync from Shopify. This re-downloads only the selected products with fresh data from Shopify.

Sync Modes

Full Sync

A full sync downloads your entire product catalog from Shopify, replacing the local cache completely. This is the most thorough sync and is used when:

You connect to a store for the first time
No previous sync has been recorded
You manually trigger a full sync from the Sync dropdown
It has been more than 7 days since the last full sync

Full sync captures every product with all variants, images, metafields, collections, and publication data.

Quick Sync (Delta)

A quick sync only downloads products that have changed since your last sync. This is much faster than a full sync, especially for large catalogs where only a few products have been updated.

Quick sync:

Checks for products updated or created since the last sync
Downloads only those changed products
Updates them in the local cache
Checks for deleted products and removes them from the cache
Includes a safety overlap period to avoid missing changes

When quick sync runs automatically: After your first full sync, subsequent syncs on startup use quick sync by default. This means you get up-to-date data in seconds rather than minutes.

Smart strategy selection for quick sync: If more than 500 changed products are detected during a quick sync, it automatically switches to Bulk Operations for that run. This threshold is separate from the full sync auto-detection threshold and ensures large batches of changes are handled efficiently.

When to Use Each

Situation	Recommended Sync
First time connecting to a store	Full Sync (automatic)
Daily startup	Quick Sync (automatic)
You suspect data is out of date	Quick Sync from toolbar
Cache seems corrupted or incomplete	Full Sync from toolbar
Many changes made outside the app	Quick Sync (catches all changes)
Store has not been synced in over a week	Full Sync (automatic)

Sync Strategy: Standard API vs. Bulk Operations

HF Product Manager uses two different methods to download data from Shopify, and automatically picks the best one for your store.

Standard API

Uses paginated GraphQL queries to fetch products in batches (50 per page). Best for:

Small to medium stores (under ~8,000 total data objects)
Quick sync with few changed products
Faster startup for small catalogs

Bulk Operations

Uses Shopify's Bulk Operations API, which runs a query on Shopify's servers and produces a downloadable file with all the results. Best for:

Large stores (8,000+ total data objects)
Stores with many variants, images, or metafields per product
First-time full syncs of large catalogs

Auto-Detection (Recommended)

The default setting is Auto, which analyzes your store's complexity to choose the best strategy. The analysis works in three stages:

Product count -- If the product count alone exceeds the threshold, Bulk Operations is used immediately without further analysis
Historical data -- If a previous sync exists, the known variant/image/metafield counts are used to calculate total data objects (zero additional API calls)
Sampling -- For first-time syncs of medium stores, the first 50 products are sampled to estimate variant density, then extrapolated to the full catalog

Total data objects = products + variants + images + metafields. If the total is 8,000 or more, Bulk Operations is used; otherwise, Standard API is used.

You can override auto-detection in Settings if you prefer to always use one strategy. The threshold is adjustable from 2,000 to 20,000 objects.

Variant Metafield Override

If your store has variant metafield definitions (custom metafields on variants, not just products), the sync always uses Bulk Operations regardless of the threshold or strategy setting. This is because the Standard API cannot efficiently fetch variant-level metafields -- each variant would need a separate query. The Bulk Operations path handles variant metafields natively in a single download.

This override is automatic. You do not need to configure anything -- the app detects variant metafield definitions and switches strategies on its own.

Sync Progress

When a sync runs, a progress modal shows the current status. The exact steps depend on whether Standard API or Bulk Operations is used.

Standard API Sync Steps

Checking store size -- Querying Shopify for the product count and analyzing store complexity (Auto mode only)
Fetching products -- Downloading products in paginated batches (50 per page)
Saving to cache -- Writing product data to the local SQLite database
Syncing collections -- Downloading collection definitions and product-collection memberships
Syncing publications -- Downloading sales channel assignments for each product
Detecting deleted products -- Comparing cached product IDs against Shopify to remove products that no longer exist
Caching thumbnails -- Downloading product images for fast grid display
Syncing inventory -- Updating inventory levels (if inventory sync is enabled)

Bulk Operations Sync Steps

Checking store size -- Analyzing store complexity to confirm Bulk Operations is appropriate (Auto mode only)
Initiating bulk operation -- Submitting the bulk query to Shopify's servers
Waiting for Shopify -- Polling every few seconds until Shopify finishes processing the query
Downloading results -- Downloading the JSONL results file from Shopify's CDN
Parsing data -- Stream-parsing the JSONL file into product, variant, image, and metafield objects
Saving to cache -- Bulk-upserting all products into the local SQLite database
Syncing collections -- Downloading collection definitions (product-collection mappings are included in the JSONL data)
Syncing publications -- Fetching sales channel assignments via a separate Standard API pass (see note below)
Detecting deleted products -- Comparing cached product IDs against the downloaded set to remove stale entries

Why publications require a separate pass: Shopify's Bulk Operations API limits queries to 5 connected resource types (known as the "5-connection limit"). The bulk query already uses its connections for variants, images, metafields, variant metafields, and collection memberships. Publication data cannot fit within this limit, so it is fetched afterward using the standard paginated API. This adds a short extra step but ensures all sales channel data is captured.

Each step shows its progress and estimated time remaining. You can cancel a sync at any time. If a Bulk Operations sync fails at any point, the app automatically falls back to Standard API sync.

Multi-Store Sync

If you have multiple stores connected, HF Product Manager can sync all of them automatically.

How Multi-Store Sync Works

When the product sync mode is set to On Startup (All Stores), all connected stores are synced when the application starts
The active store syncs first so you can start working as soon as possible
Remaining stores sync in sequence after the active store finishes
Each store runs a quick sync (delta), downloading only what changed since that store's last sync
Inventory is synced for each store as part of the process (unless set to Manual Only)

For a single connected store, the sync behaves normally with no multi-store window.

Multi-Store Progress Window

When two or more stores are being synced, a dedicated progress window appears showing:

Store list -- All stores being synced with their current status: Waiting, Syncing, Completed, or Failed
Step detail -- Detailed progress for whichever store is currently syncing (checking for updates, saving to cache, caching thumbnails, syncing inventory)
Results per store -- Product count and elapsed time for each completed store
Summary -- When all stores are done, a summary shows how many succeeded, failed, and total products synced

If one store fails (for example, due to expired credentials), the sync continues to the next store. Failed stores show their error message in the progress window. You can cancel the entire multi-store sync at any time.

Triggering Multi-Store Sync

Multi-store sync runs automatically based on your product sync mode setting. If you want to trigger it manually, use the Sync Now button in the toolbar -- it syncs the current store. To sync all stores manually, you can switch the sync mode to On Startup (All Stores) and restart, or sync each store individually by switching to it and clicking Sync Now.

Sync Settings

Sync behavior is configured in Settings > Sync Tab. See Settings for full details on all options including:

Product sync mode (when to sync)
Product loading strategy (Standard API vs. Bulk Operations)
Auto-detection threshold
Inventory sync mode and strategy
Sales data sync mode

Deleted Product Detection

During quick sync, HF Product Manager checks for products that were deleted from Shopify since the last sync. It compares the product IDs in Shopify against the local cache and removes any that no longer exist.

Safety guards prevent accidental mass deletion:

If Shopify returns zero products but the cache has data, deletion is skipped (likely an API failure)
If deletion would remove more than 50% of cached products, it is skipped to protect cache integrity

Troubleshooting

Sync seems slow

Check your loading strategy. If you have a large store (thousands of products with many variants), switch to Bulk Operations in Settings > Sync > Product Loading Strategy. The Standard API fetches 50 products per page, which adds up for large catalogs.
Quick Sync should be fast. If quick syncs are slow, it may be because many products changed since the last sync. This is normal after a large import or bulk update in Shopify admin.
First sync is always the slowest. After the initial full sync, subsequent syncs use delta mode and are much faster.

Sync shows wrong product count

Quick sync only updates changed products. The product count shown after a quick sync is the number of products that were updated, not the total in your store. The total is shown in the grid status bar.
Try a full sync. If the grid seems to be missing products, run a Full Sync from the toolbar dropdown to re-download everything.

Sync fails with an error

Check the activity log at %LocalAppData%\HFProductManager\Logs\activity.log for detailed error messages.
Token expired. If you see authentication errors, go to Settings > Stores and click Refresh Token.
Rate limiting. If you see throttling errors, try again in a few minutes. Bulk Operations strategy is less affected by rate limits.

Multi-store sync fails for one store

The sync continues to the next store automatically. Check the failed store's error in the progress window.
Common causes: expired token, changed API scopes, or store temporarily unavailable.
After the sync completes, switch to the failed store and try syncing it individually.

Products deleted from cache unexpectedly

The safety guards should prevent this. If you see unexpected deletions, check the activity log for "CheckAndRemoveDeletedProducts" entries.
If needed, run a Full Sync to restore the complete catalog.

Tips

Quick sync is usually all you need. It catches all changes including new products, updated products, and deleted products.
The first sync takes the longest. After that, quick syncs are fast because they only download what changed.
Sync before bulk operations. If you have been making changes in the Shopify admin, sync first so HF Product Manager has the latest data.
Check the activity log if a sync fails. The log is at %LocalAppData%\HFProductManager\Logs\activity.log.