Forking a template

Forking creates a tenant-owned copy of a global mapping template that you can edit freely. The original global template stays intact and keeps serving every other tenant.

When to fork

Fork when the merchant’s data needs a transform the global template doesn’t produce. Common triggers:

• A custom Magento attribute that needs to land in a specific Shopify metafield.
• An image CDN with a different host than the source store URL.
• Localized option values the global mapping doesn’t normalize.
• A bespoke discount-rule structure.

When not to fork

• The default looks slightly different but the merchant doesn’t care about the difference. Don’t fork to satisfy taste.
• The merchant wants a feature that should exist for everyone. File it as a request to improve the global template instead — every tenant benefits.
• You haven’t run an extract yet. Always fork against real data.

How to fork

From the mapping detail page, click Fork. The wizard:

1. Names the fork after the migration by default. Rename if you want to reuse the fork across multiple migrations in your tenant.
2. Copies the current global version into the new fork as version 1.
3. Repoints this migration’s mapping at the fork.

Sharing a fork across migrations

A fork is a tenant-owned template — once created, it shows up in the template picker for any of your migrations. To pin another migration to the fork, open that migration’s mapping and Switch template.

Pulling in upstream changes

The global template will keep evolving. Forks don’t auto-update. To re-base a fork on a newer global version:

1. Open the fork. Note the upstream template + version it diverged from.
2. Manually apply the upstream changes you want — the editor’s diff view across versions makes this tractable.
3. Save as a new fork version.

For now this is a manual step. Automated re-base is on the roadmap.