- Choose an explicit source of truth for every catalogue field before writing the connector.
- Build a repeatable synchronisation module, not a one-off import script with no second run.
- Preserve stable external identities so updates do not create duplicate products and variants.
- Translate Shopify’s catalogue model into Medusa deliberately instead of copying payloads blindly.
- Use reconciliation and operator visibility to make partial failures repairable.
The client problem: the new capability could not wait for a perfect migration
Shopify was already useful to the business. Products existed, the team knew its interface and daily catalogue work continued there. At the same time, the next commerce initiative needed workflows that did not fit comfortably inside the existing storefront: private B2B buying, operator tools and custom automation around the same products.
Treating the decision as ‘Shopify or Medusa’ would have forced a large migration before the client could test the new value. We chose a staged architecture instead. Shopify remained an authoritative catalogue source for the agreed fields, while Medusa received a synchronised representation that could participate in the new commerce system.
Define ownership before moving data
Store Shopify product and variant identifiers as durable external references. Handles and titles are readable, but they are not safe update keys.
Decide whether Shopify owns titles, descriptions, media, options and translations, and whether any Medusa fields are allowed to diverge.
Prices, markets and stock may follow a different owner from descriptive content. The connector must not overwrite them simply because they appear in one payload.
Create, update, archive and deletion need separate policies. Missing from one response is not automatically permission to erase a sellable product.
Build a synchronisation capability, not a disposable migration script
A one-off script is judged by whether it finishes once. A connector must survive its second and hundredth runs. It needs stable matching, normalisation, pagination, bounded batches, retry behaviour and a record of what changed. Re-running the same source data should update or skip existing records rather than manufacture duplicates.
We placed the integration behind a Medusa module so its source client, mappings and state had an explicit boundary. Products and variants were transformed into the target model rather than written as raw Shopify payloads. The pattern could then support an initial import, incremental refreshes and later reconciliation through the same contract.
This also made the integration reusable. The valuable asset was not a file that happened to move one catalogue. It was a controlled bridge that another project could configure, observe and extend.
See the original Shopify-to-Medusa module
Product models look similar until the edge cases arrive
Both platforms have products, variants, options, images and prices, but their contracts are not interchangeable. Options need stable ordering. Variant combinations need to resolve to the right option values. Media ordering and featured images affect presentation. Status and publication concepts do not always carry the same meaning.
International content adds another layer. In the later evolution of this connector, 629 Shopify products were synchronised with translations using Medusa’s translation management. That was valuable because localisation stayed connected to catalogue identity instead of becoming a parallel copy assembled by the storefront.
A robust mapping documents every transformation and every unsupported field. When the source contains an unfamiliar shape, the connector should record the exception for review. Guessing makes the first demo look complete and the production catalogue gradually less trustworthy.
Combine events with reconciliation instead of trusting either alone
After the initial catalogue load, the system needs to know what changed. Shopify webhooks can deliver product updates quickly, but an event can arrive twice, arrive out of order or fail during an outage. A scheduled full import is slower and more expensive, but it can discover drift that an event path missed.
We use the two mechanisms for different jobs. Events trigger focused refreshes using the stable source identity. Each refresh reads the current Shopify representation rather than assuming the event payload contains the complete truth. Periodic reconciliation scans the catalogue in bounded pages and compares source versions or normalised projections with known Medusa records.
Idempotency belongs at item level. Replaying the same update should lead to the same target state and a visible unchanged outcome. Ordering needs protection too: an older job must not overwrite a newer source version simply because it finished later. These rules turn eventual consistency from a slogan into behaviour the team can operate.
Design the bridge so the business keeps future options
A hybrid architecture becomes dangerous when nobody can say how it ends. The connector should expose which domains still depend on Shopify, which have moved to Medusa and what would be required to change ownership. That map lets the company evaluate migration by capability rather than planning one dramatic cutover around the entire catalogue.
One path is permanent coexistence: Shopify remains the merchandising interface and Medusa consumes the catalogue for custom channels. Another path gradually moves translations, pricing or stock into their new authoritative systems. A final path migrates catalogue ownership completely once the new operating model is ready. The same stable identities and reconciliation history support all three.
This flexibility has commercial value. The client can launch the workflow that creates differentiation now, observe how teams use it and postpone irreversible migration work until there is a reason to do it. The bridge is successful when it reduces dependency without creating a new hidden dependency on the bridge itself.
Make the bridge observable enough to repair
Catalogue synchronisation is rarely all-or-nothing. One product can contain invalid data while hundreds of others are valid. A remote API can rate-limit one page. An image can fail after the product record succeeds. If the only state is ‘sync failed’, operators either rerun everything or search logs until they find the missing item.
The integration should expose a run summary and item-level outcomes: created, updated, unchanged, skipped or failed with a reason. A reconciliation pass compares known external identities against Medusa and highlights drift. The team can then retry a bounded set instead of treating the whole catalogue as suspect.
Why using two platforms was a deliberate architecture choice
The value of Medusa here was not that it could imitate Shopify. It was that we could extend it around the client’s new workflows while respecting an existing source that still served the business. The catalogue bridge bought time and reduced transformation risk: new capabilities could be built without demanding that every team change tools on day one.
This hybrid shape is not automatically the permanent answer. It is a controlled stage with explicit ownership. Because the connector preserves identities and mappings, the client can later move more authority into Medusa, keep Shopify as a source, or retire the bridge deliberately. Architecture creates options when it makes boundaries visible.
Common questions
Not necessarily. A migration transfers ownership. A synchronisation can let Shopify remain authoritative for selected catalogue fields while Medusa powers new workflows.
Handles and titles can change or collide. Stable source identifiers let repeated runs update the correct product and variant without relying on presentation fields.
Yes. Field-level ownership is essential in a hybrid system. The connector should update only the domains Shopify is meant to own and leave other commercial data to its authoritative system.