May 3, 2026

Sanity Connect for Shopify: A Working Implementation Guide

Configure Sanity Connect for Shopify: content ownership, metafield import, sync modes, document mapping and checks before launch.
7 min read
Flux Insights Static Hero
Adam Tregear
Founder @ Flux

Sanity Connect links Shopify commerce data with Sanity content. The important setup decisions are what each system owns, which data syncs in each direction, and how the storefront stays current.

This guide covers those decisions and the checks we use before launch: document mapping, metafields, sync mode, monitoring and reconciliation. Start with the current integration before building a custom replacement.

What Sanity Connect actually does

‍

Sanity Connect is a free Shopify app published by Sanity. Check its current configuration options before scoping custom sync work.

  • Map Shopify commerce data into the chosen Sanity dataset.
  • Choose the sync method and whether updates run automatically or manually.
  • Select the supported metafield namespaces to import.
  • Configure any custom Sanity content that should be delivered back to Shopify.
  • Test publication, deletion and storefront behaviour with the actual schema.

‍

Keep ownership explicit. Shopify-managed commerce fields and Sanity-authored content can travel in different directions; that does not mean any edit to a synced Shopify field should overwrite its source.

‍

If you're new to the broader stack, our post on why Sanity is the best headless CMS for Shopify covers why this is the right shape for the integration in the first place.

‍

The data model Connect creates

‍

The default reference model uses product and productVariant types with commerce fields under store. The example below illustrates a custom wrapper model, not the default Connect payload. Match any implementation to the configured schema.

// shopifyProduct (auto-created)
{
  _type: 'shopifyProduct',
  shopifyId: 'gid://shopify/Product/12345',
  shopifyHandle: 'merino-crew-sweater',
  title: 'Merino Crew Sweater',
  productType: 'Sweater',
  vendor: 'Brand',
  status: 'active',
  variants: [{ _ref: 'variant_12345_1', _type: 'reference' }],
  updatedAt: '2026-05-01T08:00:00Z'
}

// shopifyProductVariant (auto-created)
{
  _type: 'shopifyProductVariant',
  shopifyVariantId: 'gid://shopify/ProductVariant/12345-1',
  sku: 'MCS-CHA-M',
  title: 'Charcoal / M',
  price: 189.00,
  inventoryId: 'gid://shopify/InventoryItem/...',
  parent: { _ref: 'product_12345', _type: 'reference' }
}

‍

Keep the integration-managed commerce fields separate from your editorial fields. If you use a separate enrichment document, make its references and lifecycle explicit so a resync does not overwrite content.

‍

Check 1: Decide which system owns each field

‍

Shopify remains the source for its synced commerce data. Connect can also deliver configured custom Sanity content to Shopify as metafields and metaobjects. These are distinct paths, not unrestricted two-way editing of a product.

‍

Document the owner and destination for each field. Rich story blocks, lifestyle images and care content can be Sanity-authored while commerce values remain Shopify-managed.

‍

Make this rule explicit with the content team before launch. We've seen new merchandisers spend an hour rewriting product descriptions in Sanity, only to watch them disappear when Shopify pushes the next sync.

‍

Check 2: Map the variant fields you actually need

‍

Use the configured variant model and current reference, not an assumed fixed payload. Check identifiers, images, availability and the fields your storefront consumes.

‍

For live commerce decisions, query Shopify through the Storefront API as appropriate. Decide separately which variant imagery, copy and merchandising fields the editorial team needs to maintain.

‍

If the required mapping is not covered, evaluate a custom sync handler or separate enrichment fields before replacing the entire integration.

‍

Check 3: Configure supported metafield import

‍

Connect can import selected product and collection metafield namespaces into a read-only store.metafields array. Variant metafields and Shopify metaobjects are not currently included in that inbound import.

‍

Work through the mapping in order:

  1. Choose the source of truth for the content.
  2. Select supported namespaces and test the resulting documents.
  3. Run a resync when configuration changes need to apply across the catalogue.
  4. Use a custom mapping or direct storefront query only for requirements the configured integration does not cover.

‍

Which one you pick is a function of how often the metafields change, who edits them, and whether the data is reused across surfaces. The deeper comparison between metafields and Sanity as content stores lives in Sanity vs Shopify metafields.

‍

Check 4: Distinguish sync state from storefront state

‍

Check whether automatic or manual sync is configured before treating a missing update as a failure. Then compare the source product, Sanity document and rendered storefront. A stale cache and missing data are different problems.

‍

Checks when an update is missing:

  • The sync mode or selected data does not match the requirement.
  • A schema change no longer matches the incoming mapping.
  • A downstream write or validation fails.
  • The document updates, but the storefront cache still serves old content.

‍

These checks help locate stale data before choosing a repair. We've seen drift of 5-15% of products after six months on builds that didn't have reconciliation in place.

‍

The reconciliation pattern

‍

Where freshness requirements justify it, add reconciliation. Define the fields owned by the integration, compare representative data and alert on unresolved differences. A nightly job is one pattern, not a substitute for checking the configured sync.

  1. Read the source records through the supported Shopify API, including pagination.
  2. Read the matching Sanity documents using the actual schema and identifiers.
  3. Compare only the fields the integration owns.
  4. Repair through a supported sync or carefully scoped update.
  5. Log failures and review unresolved differences.
  6. Alert if drift exceeds a threshold (we use 1% of catalogue).

The example below is illustrative pseudocode using custom helper methods and a wrapper schema. It is not a drop-in Shopify SDK implementation. A production repair must preserve editorial fields rather than blindly replacing whole documents.

Pseudocode:

// reconcile.ts (runs nightly)
const shopifyProducts = await shopifyAdmin.products.list({ status: 'active' })
const sanityProducts = await sanityClient.fetch(
  `*[_type == "shopifyProduct"]{ shopifyId, title, updatedAt }`
)

const sanityById = new Map(sanityProducts.map(p => [p.shopifyId, p]))
const drift = []

for (const shopifyProduct of shopifyProducts) {
  const sanity = sanityById.get(shopifyProduct.id)
  if (!sanity || hasChanged(shopifyProduct, sanity)) {
    drift.push(shopifyProduct)
  }
}

for (const product of drift) {
  await sanityClient.createOrReplace(buildSanityDoc(product))
}

await alertIfThresholdExceeded(drift.length, shopifyProducts.length)

‍

It runs in 90 seconds for a 5,000 product catalogue. It's the single highest-leverage piece of operational tooling in the entire stack. The broader integration health pattern is covered in our post on getting your back-office connected.

‍

Check 5: Test the initial import and resync

‍

Initial and manual syncs use Shopify bulk operations. Test the completion state, Sanity publication and downstream cache or search updates before launch. Catalogue size alone does not establish how long the whole workflow will take.

‍

Before the first production sync:

  • Run the first import with enough time to resolve mapping issues.
  • Check the integration's status and the storefront, rather than assuming an import creates a webhook flood.
  • Test downstream consumers against the actual events they receive.

‍

When to replace Connect with a custom sync

‍

Three triggers usually drive the conversation:

  1. Required mapping is not covered. Try supported configuration and custom handlers before committing to a replacement.
  2. Content ownership is unclear. Resolve that design problem before adding another sync layer.
  3. Several stores share a model. Define identifiers, references and ownership per store, and test whether the selected setup fits.

‍

Below those triggers, Connect plus a reconciliation job is the right answer. It's free, supported, and battle-tested. Don't build a custom sync because it feels more sophisticated. Build one because Connect specifically can't do what you need.

‍

The launch checklist

‍

Five things we run before going live with Connect on any new build:

  • Document field ownership and both configured directions.
  • Run a 14-day pre-launch sync and investigate discrepancies.
  • Deploy the required monitoring and reconciliation without overwriting editorial data.
  • Confirm metafield namespaces, mapping and resync behaviour.
  • Review Connect status and relevant delivery evidence; it does not require merchant-managed HTTPS webhooks in Shopify Admin.

‍

Get those five things right and Connect runs quietly in the background for years. Skip them and you find out about the gaps when a customer support ticket forces the issue. Talk to our team if you want help running this in production.

Frequently asked questions

Is Sanity Connect free?

Yes. Sanity Connect is a free Shopify app published by Sanity. The cost is your Sanity dataset usage and the engineering time to build around it. No additional licensing.

Can I edit a product in Sanity and sync the change back to Shopify?

Synced commerce fields remain Shopify-managed. Connect can also deliver configured custom Sanity fields and documents back to Shopify as metafields and metaobjects. That is not unrestricted two-way editing of a Shopify product; document field ownership before enabling either direction.

How does Sanity Connect handle product variants?

Use the current configured model and reference rather than assuming every setup uses the same shallow wrapper document. Check the fields your storefront needs and enrich or customise the mapping where necessary.

Does Sanity Connect sync Shopify metafields?

Yes, when configured. Selected product and collection namespaces can be imported into a read-only store.metafields array. Inbound variant metafields and Shopify metaobjects are not currently supported. Test the mapping and resync after configuration changes.

What happens when I delete a product in Shopify?

The corresponding Sanity document is soft-deleted: a deleted flag is set on the document, but the document itself remains in Sanity. This is intentional, so you can preserve enriched content in case the product is restored. To hard-delete, you remove the document manually or via a script.

How often does Sanity Connect sync changes?

It depends on sync mode and workload. Automatic sync responds to product and collection changes; manual mode needs a sync run. Initial and manual imports use Shopify bulk operations. Measure the complete path to the storefront instead of promising a fixed delay.

Why do my Sanity documents drift out of sync with Shopify over time?

First check sync mode, selected data, mapping and storefront caching. Compare source and destination values before repairing anything. Our practice is to add reconciliation and alerts where freshness requires it; keep repairs limited to integration-owned fields so editorial content survives.

When should I replace Sanity Connect with a custom sync?

Replace it only for a verified requirement that configuration, enrichment or a custom sync handler cannot meet. Metafield import and outbound custom-content delivery are supported capabilities, so they are not by themselves reasons to build a replacement.

/score

Does AI recommend your brand?

We ask ChatGPT and Perplexity 10 real buying questions for your category and score you against your biggest competitor. Live, in about 2 minutes.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

Free. Enter your store's website, e.g. yourstore.com

Flux is a Shopify Plus Agency for Advanced Engineering & AEO

TLDR Summary
  • Keep Shopify-managed commerce data separate from Sanity-authored content, with one documented owner for each field.
  • Connect supports selected Shopify metafield import and configured custom-content delivery back to Shopify.
  • Check the actual document model, sync mode and field mapping rather than copying an assumed payload.
  • Monitor source data, Sanity state and storefront caching separately; reconcile where freshness requirements justify it.
  • Keep the 14-day pre-launch check, test resync and avoid repairs that overwrite editorial content.
  • Use a custom replacement only for a requirement the supported configuration or handlers cannot meet.