Skip to main content

Sync your catalog

Plans: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓ (catalog cap varies by plan — see Plans)

Sync pulls your products, categories (or collections, on Shopify), content pages, and FAQs from your store into Clione. Nothing is enriched yet — sync just builds Clione's working copy so the rest of the platform has something to operate on.

You sync per store, and per entity type. Open any store in the sidebar, then click Sync.

The Sync page has four tabs:

  • Products
  • Categories (BigCommerce) / Collections (Shopify)
  • Pages
  • FAQs (only if your platform stores native FAQ pages — most don't, so this tab is informational)

Each tab runs independently. You can sync only what changed without re-pulling the whole catalog.

When to run a sync​

  • First time you connect a store. Run all three (Products, Categories/Collections, Pages) so Clione has the full picture.
  • After bulk changes in your e-commerce admin. New product line, category re-org, page rewrites — sync after to bring Clione up to date.
  • Before bulk-enriching. If you just imported 200 SKUs, sync them in before enriching, or Clione will only enrich what it already knew about.
  • Anytime "stale data" suspicions appear. When the dashboard shows an out-of-date title or description for an entity you know was changed in your store admin, run a sync for that entity type.

You do NOT need to sync to use the FAQ editor, the URL Verifier, Reports, or any of the platform-wide tools. Sync only touches the catalog mirror.

BigCommerce​

Products​

  1. Open the store → Sync → Products tab.
  2. Click Sync products.
  3. The progress chip in the top bar shows real-time status (running, pages processed, errors). It survives navigation — you can leave the page and come back.

What's pulled per product:

  • ID, name, SKU, vendor, brand
  • Price + currency
  • Description (HTML), short description
  • Categories the product belongs to
  • All SEO metadata: page_title, meta_description, search_keywords, meta_keywords, custom_url, all open_graph_* fields
  • Image URLs (primary + variants)

Categories​

  1. Sync → Categories tab → Sync categories.
  2. The full category tree is pulled (parent IDs preserved). Read-only categories and visibility flags come too.

Note: BigCommerce category custom_url is read-only via the public API and arrives as { url, is_customized }. Clione respects whatever the store currently has — it does not rewrite category URLs.

Pages​

  1. Sync → Pages tab → Sync pages.
  2. BigCommerce returns content pages (About, Contact, custom pages — not blog posts).

FAQs​

BigCommerce doesn't expose native FAQ entities, so this tab shows informational text only. Clione's FAQ feature lives under FAQs (in the sidebar of each store) and is platform-agnostic — see FAQ editor + embed widget.

Shopify​

Products​

  1. Open the store → Sync → Products tab.
  2. Click Sync products.

What's pulled per product:

  • ID, title, handle, vendor, product type, tags
  • Price + currency (default variant)
  • Description (HTML)
  • All SEO metafields under the global namespace (title_tag, description_tag)
  • Image URLs
  • Variant list (multi-currency support is planned — see Plans)

Collections​

  1. Sync → Collections tab → Sync collections.
  2. Both manual (custom) and smart (automated) collections are pulled. The rules of smart collections are stored so Clione knows which products belong without re-asking Shopify on every request.

Pages​

  1. Sync → Pages tab → Sync pages.
  2. Shopify returns content pages (About, Contact, Help — not blog articles).

FAQs​

Same as BigCommerce — this tab is informational. Use the FAQ editor for managed FAQs.

Watching progress​

While a sync is running:

  • A chip appears in the top-right of the dashboard with the entity type and a spinner.
  • Hovering shows "synced N / total" and any errors.
  • The chip persists across page navigation (you can switch tabs and come back).
  • When sync finishes, the chip turns green and auto-dismisses after a few seconds. The listing pages (Products, Categories, Pages) automatically refresh so you see the new data without a manual reload.

If a sync fails partway through (e.g. a transient 429 from the store API), the entities already synced are kept. Click Sync again to resume — Clione is idempotent and only updates rows where the upstream updated_at is newer than what's in our DB.

How long does it take?​

Rough estimates per 1,000 entities (network and platform-dependent):

EntityBigCommerceShopify
Products30–60s60–120s
Categories / Collections< 5s< 10s
Pages< 5s< 5s

Shopify is slower per call because their GraphQL API rate-limits via cost, not requests-per-second. Clione retries with backoff automatically when it hits the cost limit, so a 5,000-product sync can take 5–10 minutes on Shopify.

Re-sync vs partial sync​

Today, sync is always full-pass: Clione walks every page of the upstream API and upserts every record. This is intentional — incremental sync via webhooks is a planned addition but the current model is simpler and guaranteed to converge.

If you only changed a handful of products in your store admin and want to see them in Clione without re-syncing thousands, you can:

  1. Open the entity directly by name from any listing.
  2. Click Refresh from platform in the entity detail header. This re-pulls that one entity from BC/Shopify and updates the mirror.

Troubleshooting​

Sync says "no credentials" or "401" — The access token has been revoked on the platform side, or has expired. Re-add the credential under Store → Settings → Credentials.

Sync runs but the entity count doesn't match my store — Some entities may be hidden from the API (e.g. drafts, deleted-but-not-purged). Filter your store admin by "active / visible" status to compare like with like. If the gap persists, contact support with the store ID and a few sample SKUs that should appear but don't.

Sync stuck on 99% — One specific entity is failing to upsert (usually a malformed image URL or a too-long field). Open the dashboard browser console (F12 → Console tab) and look for the row that errored — the message includes the entity ID. Fix that record in your store admin and re-sync.

"Enrichment shows 0/0 even after syncing" — Known issue (#87). Sync wrote the entities but the overview counter is reading from a stale cache. Refresh the page once; if it persists, this is the bug we're tracking — please report with the store ID.

API endpoints touched per platform​

For troubleshooting and for understanding the scopes required, here are the platform endpoints each sync hits.

BigCommerce (REST v3)​

  • GET /v3/catalog/products?limit=250&page=N&include=variants,images,custom_fields,bulk_pricing_rules,options,modifiers,videos — paginated walk.
  • GET /v3/catalog/brands — for vendor resolution.
  • GET /v3/catalog/categories?limit=250&page=N — flat list of category nodes.
  • GET /v3/catalog/categories/tree — tree shape for parent/child links.
  • GET /v3/content/pages?limit=250&page=N — content pages.
  • GET /v3/catalog/products/:id/metafields?namespace=clione — to read back what Clione previously wrote.

Required scopes (from the BC Store API account):

  • Products: Read/Write
  • Information & Settings: Read
  • Content: Read
  • Customers: None
  • Orders: None
  • Marketing: Read (only if Promotions is in use)

Shopify (Admin GraphQL 2024-10)​

  • query { products(first: 250) { ... } } — paginated walk with pageInfo.
  • query { collections(first: 250) { ... } } — both manual and smart.
  • query { pages(first: 250) { ... } } — content pages.
  • query { shop { primaryDomain, currencyCode, ... } } — shop metadata.
  • query { metafields(...) } — read back Clione's metafield namespace.

Required scopes (from the Shopify Custom App):

  • read_products, write_products
  • read_content, write_content
  • read_themes, write_themes (write_themes optional but recommended)
  • read_online_store_pages
  • read_locales

Sync logs​

After every sync, an entry appears in the Sync history panel on the Sync page. Each entry shows:

  • Start + end timestamps
  • Entity type
  • Entities processed / created / updated / errored
  • Per-error rows with the offending entity ID and the platform's response

Entries persist for 30 days. Filter by entity type or by "errors only" to triage.

Concurrency​

You can run only one sync per entity type per store at a time. If you click Sync while one is in progress, the button is disabled and a tooltip explains. Multiple stores can sync in parallel.

Across all stores in your tenant, the global sync concurrency is 4 (one per CPU core on our sync workers). The 5th + queued syncs start as earlier ones finish.