Shopify Migration: Preserving Customer Stages

This guide is for existing Northbeam customers migrating from a custom order management system using Orders API to Shopify.

It covers one specific task: preserving your historical Customer IDs so Northbeam can continue accurately classifying customers as New or Returning after migration.

This guide does not cover full order or customer data migration into Shopify..

Why this matters

Shopify generates its own unique Customer IDs when customer records are imported. Northbeam relies on consistent Customer IDs to determine whether a customer is New or Returning.

Without this step, every existing customer will appear as a New customer in Northbeam — because Shopify-generated IDs have never been seen before.

To prevent this, you'll store your historical Customer IDs in a Shopify customer metafield, which Northbeam's engineering team will then map to your existing customer records.

Before You Start

Make sure you have:

• Access to your Shopify admin
• A customer export from your previous system with Customer IDs and email addresses intact
• Your Northbeam pixel still active on your storefront

🚧

Important: Do not remove the Northbeam pixel until your Shopify integration is fully verified. Running both systems in parallel during the transition prevents gaps in attribution data.

Step 1: Create a Customer Metafield in Shopify

Do this before starting your migration.

1. Login to your Shopify store at shopify.com if you haven't already

   

2. Click on Settings — find this in your Shopify homepage on the bottom left corner

3. Click on Customers

   

4. Click Add definition If you haven't added one before, this button will be center-stage!

   

5. Customer Metafield Details

   1. Name: legacy_customer_id — note this name exactly, you'll need it later.
   2. Type: Single line text
   3. Validation: minimum of 1 and max of 256

6. Click Save

The metafield namespace will default to custom, making the full field key customer.metafields.custom.legacy_customer_id

This is the column header you'll use in your CSV import.

Step 2: Export customer data from your current system

Before disconnecting your old system, export your customer list. At minimum, your export must include:

• Customer ID (from your legacy system)
• Email address

Store this export securely — you'll use it to populate the import file in Step 3 and to verify your data in Step 4.

⚠️

Do not remove the Northbeam pixel from your website until your Shopify integration is fully verified. Running both in parallel during the transition prevents gaps in attribution data.

Step 3: Format Your Customer List for Shopify

Use the Northbam Shopify Import Tempalte to format your data

The most common formatting mistake is getting the metafield column name wrong. It must be exactly:

customer.metafields.custom.legacy_customer_id

Step 4: Import your Customers into Shopify

Proceed to your Customers page in Shopify.

1. In the top left corner, click Import:

2. Import your CSV files!

   

   _We recommend following the following template for guidance as the template that Shopify provides does not account for Customer metafields.

Step 5: Notify your CSM at Northbeam

Once your data has been uploaded, inform your CSM at Northbeam along with the name of your legacy customer_id field. Once we have this, the Northbeam engineering Team can map your old Customer IDs into your dashboard, preserving customer stages.