Skip to main content

Architecture

Product sync​

  1. Export: a Shopify bulk operation pulls products from production, streamed line by line so large catalogs fit in memory.
  2. Transform: every reference to another product, file, metaobject or collection is swapped for its staging ID, matched by handle.
  3. Import: products are created or updated on staging and published to the same sales channels.
  4. Inventory: stock levels are set on staging.
  5. Bundles: bundle products are rebuilt on staging, since the import doesn't carry bundle structure.

What gets synced​

A product is stale when production's updatedAt is newer than the timestamp stored on the staging copy. Syncs only touch stale products unless forced.

Jobs choose their scope with flags such as --category, --type, --style, --handle or --all.

Setup sync​

Staging needs the same metafield and metaobject definitions as production. If an import fails because one is missing, the sync copies the definitions over and retries the failed products.

Collection sync​

Collections follow the same export, transform and import path. Manually sorted collections take their product order from SearchSpring's merchandising when a campaign exists, otherwise from production.

Merchandising​

The merchandising job fetches SearchSpring's merchandised order for each manually sorted collection and reorders the Shopify collection to match. Collection pages can then be served straight from Shopify without calling SearchSpring at request time.

Activation sync​

Merch stages launch-day drops in production as active but unpublished, tagged with the launch date (for example 7/6/26). The normal sync skips unpublished products, so this job copies those drops to staging and publishes them there for QA. Once a drop launches, the normal sync takes over.

QA audit​

After a product sync, the audit checks every purchasable product against a set of rules (images, size range, rush fee, tags and more). Errors go to a Google Sheet tab named after the sync's scope. Warnings are counted but not written.

Webhooks​

WebhookAction
products/create, products/updateSyncs the product to staging if it's active and tagged no-index, giving it a preview URL.
orders/createUpdates gift card details on orders that contain gift cards; ignores the rest

State and alerts​

  • There's no database. Job status lives in memory and is gone when the service or job restarts.
  • Slack posts only when a run fails or reports errors: a summary, with the run's milestones in a thread. Clean runs post nothing, except the back-in-stock job, which posts the dates it set.