Any (webshop)

Platform Migration

How to migrate Clerk.io to a new eCommerce platform without losing your data, designs, or order history.

Moving your webshop from one platform to another — say, Magento 2 to Shopify, or WooCommerce to BigCommerce — involves more than just reinstalling the Clerk.io extension.

Your product IDs will likely change. Your sync method needs switching. Your designs may reference platform-specific attribute names. And your historical order data needs to carry over to keep the AI performing from day one.

This guide walks through each step.

Before Starting #

Before touching anything in Clerk.io, answer these two questions:

Will your product IDs change? Most platform migrations assign new IDs to products. This matters because Clerk.io’s AI links products to orders using the id field. If the IDs change, old orders will reference IDs that no longer exist in the new catalogue.

Can you match product IDs to order history? If you can map old product IDs to new ones (or preserve them entirely), you can keep your existing Clerk.io Store — regardless of whether the domain changes. The Store’s order history stays intact and the AI keeps its learned associations.

If the ID mapping is not feasible and you cannot reconcile old orders with new products, create a new Store in my.clerk.io and start fresh. The domain itself is not the deciding factor.

1. Map IDs #

This is the most important step. If your new platform assigns new product IDs, you need to decide how to handle the mismatch between old orders and new products.

There are two approaches:

Option A — Preserve old IDs Configure your new platform’s sync to send the same id values that were used on the old platform. Many platforms let you include a legacy or external ID field in the data feed.

Send the old platform’s product ID as id in your Clerk.io feed or CRUD API calls. Your existing order history will then still map correctly to the new catalogue.

Option B — Remap and re-upload orders If you cannot preserve IDs, you need to build a mapping table yourself — outside of Clerk.io — that translates old product IDs to new ones. Once you have that mapping, you re-upload the historical orders with the corrected IDs.

Clerk.io does not perform the mapping for you. Your developer produces a corrected set of order data, and you push it in.

Building the mapping table The easiest approach is to use the product SKU as the bridge. SKUs almost always stay the same when migrating platforms, even when internal database IDs change.

The process looks like this:

  1. Export all orders from the old platform, with each order line containing the old product ID and its SKU.
  2. Query the new platform’s database to find each product by SKU and retrieve its new ID.
  3. Replace the old IDs with the new IDs in the order data.

A simple example in pseudocode:

for order in old_orders:
    for line in order.products:
        new_id = new_platform.find_product_by_sku(line.sku).id
        line.product_id = new_id

The result is a corrected list of orders where every product reference uses the new platform’s IDs.

Pushing the corrected orders Once the mapping is done, push the corrected orders to Clerk.io. There are two ways to do this:

Via the CRUD API:

POST https://api.clerk.io/v2/order/add

{
  "key": "your_public_api_key",
  "orders": [
    {
      "id": 5001,
      "products": [901, 902],
      "time": 1622548800,
      "email": "luke@skywalker.com"
    }
  ]
}

Or via a JSON data feed that includes the full corrected orders array. The importer will process it on the next sync. This is often the simpler option for large volumes of historical orders.

Either way, 901 and 902 are the new platform’s product IDs — not the old ones.

2. Switch Sync #

Once your ID strategy is in place, update the sync method in Clerk.io to point at the new platform.

  1. Go to Data > Configuration in my.clerk.io.
  2. Change the Sync method to your new platform’s integration or feed URL.
  3. Verify the Import toggles — make sure Products, Categories, and Orders are all enabled.
  4. Update your IP allowlist if your new platform has a different server IP.
  5. Click Start New Data Sync and monitor the sync log.

After the sync completes, verify in Data > Health that product counts and order volumes look correct.

If your new platform supports it, configure realtime updates via the platform’s extension or the CRUD API so new products and orders are sent to Clerk.io as they happen — not just during the next scheduled sync.

3. Update Designs #

Designs reference product attributes using the syntax {{ product.attribute_name }}. If your new platform uses different attribute names, those references will break or render empty.

For example, a Magento 2 setup might sync a custom attribute called {{ product.manufacturer }}, while Shopify sends the same data as {{ product.vendor }}. Any design using the old name needs updating.

Finding affected designs: Use the search field on the Designs page. Search for the old attribute name — the search scans inside the HTML and CSS of all designs, so you can find every design that references it.

Updating the reference: Open each affected design and replace the old attribute name with the new one.

Using Modifiers instead: If you want to avoid editing many designs, use Modifiers to create a stable attribute in Clerk.io that maps from whatever name the new platform sends.

For example, create a modifier that copies the vendor attribute into a new attribute called manufacturer. Your existing designs then keep working without changes:

Create new attribute: manufacturer
Value: {vendor}

This is the lower-risk approach for complex setups with many designs.

4. Order Continuity #

Clerk.io stores orders independently from the product catalogue. Logged orders are never deleted when products are removed from a sync or feed — they remain as historical records and continue to influence the AI.

When you switch platforms, this means:

  • Orders logged under old product IDs remain in the Store.
  • New orders logged under new product IDs start accumulating.
  • Until enough new orders exist, you may see reduced personalisation quality for logics like Visitor Recommendations and Best Cross-Sell Products.

To accelerate this, re-import your historical orders with the new product IDs (see Step 1, Option B). This gives the AI a complete picture from day one rather than starting from scratch.

If your order volumes are high, prioritise the most recent 12–24 months of orders. Recent purchase behaviour carries more weight in the AI than older data.

5. Verify Tracking #

After going live on the new platform, confirm that sales tracking is working end to end.

Check the following:

  1. The log/sale call fires on the order confirmation page with the new product IDs.
  2. Orders appear in Data > Orders with product IDs matching the new catalogue.
  3. Data > Health shows green for Sales tracking and Clerk sales.

If tracking is broken, click-to-purchase attribution will not work and revenue impact reporting will be incomplete. The Sales Tracking guide covers how to set this up and debug it.

Example Walkthrough #

Here is how a migration from Magento 2 to Shopify looks end to end.

Before migration (Magento 2):

  • Products synced with Magento entity IDs (e.g. id: 4521)
  • Designs use {{ product.manufacturer }} for brand
  • Orders tracked via the Magento extension

Step 1 — ID mapping: Export all historical orders from Magento with product IDs and SKUs. Query Shopify to find each product by SKU and retrieve the new Shopify ID. Replace the old IDs in the order data, then push the corrected orders to Clerk.io via the CRUD API or a JSON feed.

Step 2 — Switch sync: In Data > Configuration, change the sync method from the Magento 2 integration to the Shopify integration. Run a full sync.

Step 3 — Fix designs: Search designs for manufacturer. Either replace it with {{ product.vendor }} (Shopify’s field), or add a Modifier that maps vendor → manufacturer to keep designs unchanged.

Step 4 — Verify: Place a test order on the new Shopify store. Confirm it appears in Data > Orders with the correct Shopify product IDs. Check Data > Health for green indicators.

The whole process typically takes a few hours for straightforward migrations, and a day or two for large catalogues where historical order re-mapping is needed.