Architecture
Product syncβ
- Export: a Shopify bulk operation pulls products from production, streamed line by line so large catalogs fit in memory.
- Transform: every reference to another product, file, metaobject or collection is swapped for its staging ID, matched by handle.
- Import: products are created or updated on staging and published to the same sales channels.
- Inventory: stock levels are set on staging.
- 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β
| Webhook | Action |
|---|---|
products/create, products/update | Syncs the product to staging if it's active and tagged no-index, giving it a preview URL. |
orders/create | Updates 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.