Direct answer: matching customer counts do not prove a successful migration
The goal of Shopify customer-data migration is not to display the same number of customers in a new Admin. Every customer that the business lawfully needs must retain accurate identity, addresses, consent, tags, extensions, and order relationships, while remaining explainable, accessible, and erasable. Matching counts can conceal duplicate emails, inflated consent, misplaced addresses, and broken order links.
A reliable program separates scope and legal basis, field dictionary, identity resolution, prototype, batch load, delta synchronization, cutover, reconciliation, account activation, and stabilization. Each stage has an owner, input hash, output report, privacy controls, and stop criteria. Shopify's current customer CSV documentation defines importable columns, supported metafields, password limits, and order limits. Validate against the target store's current template before writing transforms.
| Success dimension | Proof before launch | Monitoring after launch | Failure response |
|---|---|---|---|
| Identity | Unique keys, duplicate rules, human conflict queue | Duplicate creation and merge complaints | Pause delta and replay mapping |
| Consent | Source, time, channel, status are traceable | Unsubscribe, complaint, bounce | Stop sends and correct state |
| Relationships | Customer, address, order, company, tags agree | Service order lookup and account display | Repair link or use read-only archive |
| Privacy | Minimal fields, access, erasure, retention | Request SLA and unusual exports | Revoke, clean temporary files, respond |
| Recovery | Source snapshot, ID map, batches, rehearsal | Differences and errors can be replayed | Restore or compensate by batch |
Define scope and processing purpose before extracting data
Customer data should not move merely because it can be exported. Use operating countries, customer locations, contracts, service, finance, tax, marketing, and applicable law to define purpose and retention. For each field, document purpose, legal basis, source, recipient, access role, and deletion rule. Birthdays, identity documents, free-form notes, or long-inactive tags without a clear use should not be copied simply because the old system contains them.
Shopify's customer data request guidance states that merchants remain responsible for applicable privacy obligations and describes access and erasure workflows. Open access, correction, deletion, or objection requests must not disappear between systems during cutover.
Set a data freeze and privacy-request handoff
At every snapshot, record pending privacy requests, unsubscribes, merges, and deletions. Before final delta, decide which system accepts new requests and how the result reaches the target and read-only archive. Deletions and opt-outs are first-class migration events.
Build a customer object and field register
Customer information can exist in the legacy commerce platform, addresses, orders, CRM, email/SMS provider, service system, subscriptions, loyalty, B2B, forms, and warehouse. Establish the system of record for each field and whether Shopify becomes authority, consumer, or reference holder. Do not merge conflicting values without precedence.
| Data domain | Typical fields | Ownership question | Acceptance evidence |
|---|---|---|---|
| Identity | External ID, email, phone, name | Which key is stable and who changes it? | Source/target ID map and conflicts |
| Address | Company, lines, city, province, country, postcode | How are multiple addresses ordered and normalized? | Count, default, country samples |
| Consent | Email, SMS, WhatsApp, time, source | Are channel and legal basis independent? | State distribution and source proof |
| Relationship | Order, company, subscription, loyalty, service | Which system maintains it? | Bidirectional samples and business keys |
| Extension | Tags, notes, metafields, segment | Fact, calculation, or temporary label? | Dictionary, type, retention |
Make the field dictionary executable
Each row contains source field, target field, type, length, enum, null/default behavior, cleanup, transform, sensitivity, owner, and acceptance query. “Migrate directly” only transfers decisions to a developer. Every unmapped field needs an explicit retire, archive, or metafield outcome.
Minimize data and protect the migration boundary
Only place data needed for the target purpose and retention duty into the pipeline. Encrypt production exports in transit and at rest, limit access to named roles, log access and downloads, and avoid ordinary chat, email, or public spreadsheets. Prefer masked samples in development. When real data is necessary, reduce scope, isolate the environment, and set expiry.
Temporary CSV, JSONL, error files, and logs may contain personal information. Completion includes an inventory of temporary artifacts, deletion evidence, key rotation, revoked app access, and supplier-copy disposal. Removing one primary CSV while downloads and failure files persist is not cleanup.
Keep full personal data out of logs
Use source ID, target GID, batch, field, and error code to diagnose. Do not write complete email, phone, address, or notes into logs. Human review should use a controlled viewer with access evidence.
Resolve identity and duplicates before import
Email and phone can change, be reused, be absent, or appear in inconsistent formats. Names are not unique. Preserve an immutable legacy ID and map it to the Shopify GID, then use normalized email, E.164 phone, and business rules to detect candidate duplicates. Automatic merges require explainable conditions.
| Conflict | Default handling | Unsafe shortcut |
|---|---|---|
| Same email, name, address | Merge candidate; check orders and consent | Keep latest row only |
| Same email, different entity/company | Human review or isolation | Overwrite one profile |
| Same phone, different email | Check family/shared number | Treat phone as permanent unique key |
| Phone but no email | Use supported target path and consent | Invent an email |
| Guest and registered overlap | Resolve through order/account rules | Delete guest history |
Give conflicts a business decision
The queue stores conflict type, candidate records, order risk, consent difference, recommendation, reviewer, and date. A script must not silently overwrite unresolved conflict. Prioritize high-value, active subscription, refund, and B2B customers.
Normalize email, phone, names, and addresses safely
Email can be trimmed and compared under a documented case rule, but do not casually rewrite the local part. Preserve the original phone and parsed result; use source country to create an international format and send uncertain cases to exceptions. Names must support single names, compound family names, honorifics, and non-Latin characters.
Address rules cover ISO country/region, province, leading postcode zero, full-width characters, company, multiple addresses, default address, and undeliverable values. Normalization exists to support checkout, tax, shipping, and service, not cosmetic uniformity. Test with real samples from major markets.
Preserve source value and transform version
For high-risk fields, retain controlled access to source value, normalized value, rule version, and error reason. New rules can then replay rather than reverse-engineering the final state.
Migrate consent by channel and evidence
Email, SMS, and WhatsApp consent are not one Boolean. Preserve subscribed, unsubscribed, and pending states, timestamp, source form, policy version, market, and evidence separately. Shopify customer CSV has current formats for email, SMS, and WhatsApp acceptance and warns merchants to contact only customers who opted in.
If the old system contains only newsletter=true without source or time, do not promote it to every channel. Unsubscribe, complaint, hard bounce, Do Not Contact, and lawful suppression must override a subscription flag and reconcile between Shopify and marketing providers.
Treat consent distribution as a quality gate
Compare count and percentage by market, channel, and status before and after. A sudden subscription increase, disappearance of opt-outs, or concentration in a default state normally signals a mapping defect. Resolve it before any campaign sends.
Design password, account, and activation behavior
Shopify documentation states that customer passwords from another store cannot migrate through customer CSV. Never request, export, or retain plaintext passwords, and do not promise that customers can silently keep the old password. Design invitation, activation, or reset for the selected customer-account model and test it first.
Account migration also covers duplicate emails, invalid mailboxes, language templates, send rate, link expiry, service identity checks, anti-phishing copy, and alternatives for customers who cannot receive mail. Rehearsals must not send production invitations; put send switches and recipient allowlists into the runbook.
A created profile is not an activated account
A record in Admin does not prove that a customer can sign in, view appropriate orders, or manage a subscription. Test new users, migrated customers, customers without orders, multiple addresses, refunds, and subscriptions.
Use CSV for standard fields within its boundaries
Customer CSV suits conventional profiles and reviewable small-to-medium batches. Generate UTF-8 files from the target store's current template and begin with 20–100 representative records. Shopify documents that the Email column must exist, files have size limits, and certain metafield types are supported, while passwords, orders, Total Spent, and Total Orders cannot be imported as old-platform facts through customer CSV.
| CSV decision | Good fit | Risk or supplement |
|---|---|---|
| Standard name/email/phone/default address | Direct mapping | Preflight format, nulls, duplicates |
| Tags and notes | Small governed attributes | Do not hide sensitive or temporary data in notes |
| Supported customer metafields | Stable extensions | Define first; verify type and namespace |
| Multiple addresses/complex relationships | May be insufficient | API, app, or dedicated transform |
| Password, order, spend history | Not supported | Activation plus order/archive route |
Make every CSV batch traceable
Store source snapshot ID, transform version, input hash, row count, start/end, success, failure, skip, and error artifact. Before rerun, state whether the action is upsert, update, or create so a correction file cannot create a second customer population.
Govern API and migration-app flexibility
Complex relationships, multiple addresses, continuous delta, or large volume can use an app or GraphQL Admin API. Shopify's customerSet mutation creates, updates, or upserts a customer from an external source and returns field-level user errors. API availability does not guarantee correctness: govern versions, access scopes, rate behavior, idempotency, retries, results, and protected customer data.
For an app, record read/write scope, storage region, subprocessors, deletion, logs, outage behavior, and contract. After migration, revoke unnecessary scopes, tokens, and app access and verify supplier deletion.
Prevent mistaken upsert with an external identity
Email or phone may change during the project. Use the source ID as primary mapping identity and normalized contacts as conflict detectors. Persist the target GID and every API user error.
Preserve order, subscription, loyalty, and company relationships
A profile must be designed with its business relationships. Customer CSV does not import historical orders or old-platform spending totals. When service needs history, use an appropriate order migration, warehouse, or encrypted read-only archive and retain the customer map. Do not write a synthetic Total Spent to imply native order history.
Subscriptions, gift cards, store credit, loyalty points, refund eligibility, and B2B company locations represent future obligations or permissions and need independent reconciliation. Define source key, target object, balance/status date, failure handling, and communication. Two platforms cannot both own a balance.
Accept relationships with service tasks
Ask service users to find a customer, verify identity, view history, process a return, identify a subscription, confirm a balance, edit an address, and process a privacy request. Passing field comparisons while service cannot work is not completion.
Govern tags, segments, notes, and metafields
Legacy tags may be facts, campaign results, temporary lists, risk markers, or obsolete automation. Classify them before migration. Stable facts can become typed metafields. Computed audiences should be rebuilt as segments or warehouse logic. Sensitive internal data requires restrictive access. One-time campaign labels can retire.
Every extension field needs namespace, key, type, definition, owner, source, update frequency, and deletion. Free-text Note must not become an unaudited database. Validate downstream filters, automation, and apps against every retained field.
Rebuild the rule before importing its result
If VIP means spend within the last twelve months, rebuild that condition instead of importing a permanent Boolean. New customers and future orders will then receive consistent classification.
Keep privacy requests, erasure, and retention operating
Shopify distinguishes access, personal-data erasure, and customer-profile deletion; some transaction facts can remain where business or law requires. Work with privacy and legal teams on the applicable procedure rather than treating a platform feature as a legal conclusion. Track customer identifier, receipt time, verification, affected systems, due date, and completion proof for every open request.
After the source becomes read-only, the team still needs to locate customers and propagate access or erasure outcomes to archive, CRM, marketing, service, and migration suppliers. Test environments containing real data are also in scope unless governed by an approved rapid-expiry process.
Draw an erasure propagation map
Map Shopify, CRM, ESP/SMS, service, subscriptions, warehouse, backups, and suppliers. Identify automatic paths, manual paths, retention exceptions, owner, and proof.
Prototype with risk-based samples and full rehearsals
Samples include duplicate email, no email, phone only, multiple addresses, special characters, languages, opt-out, SMS consent, B2B, subscription, refund, highest value, oldest record, and newest change. Start small, validate, then expand.
Run at least two full rehearsals. The first discovers field, permission, and relationship defects. The second proves repairs, duration, cleanup, and replay. Start each run from a clean target or documented baseline rather than layering failures and inferring success from counts.
Isolate production mail and automation
Disable or intercept invitation, welcome, marketing, CRM, loyalty, and subscription messages in development. Use allowlists and test domains, and inspect webhooks or Flow triggers. A rehearsal must not expose the project or harass real customers.
Capture deltas and control the cutover window
After the full snapshot, customers register, change addresses, subscribe, unsubscribe, order, refund, merge, and request deletion. Delta design captures create, update, deletion, and relationship changes with source and event time. Filtering by one commerce-platform timestamp may miss consent changes made in a marketing system.
| Stage | Source writes | Shopify writes | Quality gate |
|---|---|---|---|
| Prototype | Normal | Test sample | Fields, identity, consent, account pass |
| Full rehearsal | Normal | Isolated batch | Counts, relationships, duration, cleanup pass |
| Delta rehearsal | Normal | Controlled upsert | Create, update, delete replay |
| Final freeze | Restrict critical writes | Open after final delta | High-risk differences zero |
| Stabilization | Read-only/limited fallback | Production authority | Requests, service, marketing, orders healthy |
State the writer of record for every phase
Name whether Shopify, the old platform, CRM, or marketing system can modify email, phone, address, consent, and tags. Bidirectional sync without conflict precedence can overwrite a valid correction with an old value.
Reconcile counts, values, relationships, and behavior
Reconciliation includes total records, unique identity, field completeness, enum distributions, address count, consent distribution, tags/metafields, order relationships, errors, and privacy requests. Subscription, loyalty, and credit use independent balance totals. Every report traces to a source row, transform rule, and target GID.
| Reconciliation layer | Example measure | Pass condition |
|---|---|---|
| Count | Valid source, created, updated, skipped, failed | Equation closes; exclusions explained |
| Identity | Unique email/phone, duplicates, guest merges | High-risk conflicts zero |
| Fields | Null, truncation, enum, country, characters | Field dictionary respected |
| Consent | State by channel and market | No default inflation; opt-out wins |
| Behavior | Login, order lookup, segments, automation, requests | Representative tasks all pass |
Approve quality thresholds before import
P0 includes incorrect consent, exposed data, wrong identity overwrite, or inability to access critical orders. P1 includes broad address or relationship corruption. These reach zero. Lower-risk formatting exceptions need sign-off and a remediation date; the migration team cannot lower criteria unilaterally.
Roll back profiles, consent, and new writes carefully
Rollback is not deleting every imported customer. After cutover, Shopify may contain new profiles, addresses, consent, orders, and privacy requests. Batch markers must distinguish migrated records from real writes, with compensation, marketing pause, account communication, and retention decisions. Broad deletion creates a second loss.
Exercise a defect where a batch sets opt-ins to yes. The team must stop sends, isolate the batch, restore source status, notify owners, assess incident response, and reconcile again. Preserve proof of the rollback.
A source snapshot is not an operational rollback
A backup can restore source data but does not explain target-side orders, invitations, subscriptions, webhooks, and sends. The runbook needs cross-system compensation order and owners.
Operate a 72-hour and 30-day stabilization period
For 72 hours, monitor import errors, duplicates, activation, login, bounces, unsubscribes, complaints, service lookup, order links, webhooks, API failures, and privacy requests. Reconcile new, changed, and merged customers and consent distributions daily. Stop affected automation before an issue expands.
Within 30 days, delete temporary files, revoke access and tokens, verify supplier disposal, establish read-only source policy, rehearse a privacy request, and obtain final sign-off. For whole-store object, URL, and cutover practice, use the governed Magento-to-Shopify migration guide. WESWOO's migration services and Shopify store setup guides can help structure implementation.
A 30/60/90-day implementation route
In days 1–30, confirm scope, data flow, field dictionary, identity rules, consent evidence, privacy requests, tools, and samples. In days 31–60, build a masked prototype; transform profiles, addresses, metafields, and relationships; test accounts and notifications; run the first full load and reconciliation. In days 61–90, run the second full load, delta, load, security, privacy, rollback, and cutover rehearsals, then lock stabilization and source exit.
Actual timing depends on volume, source systems, B2B, subscriptions, markets, and law. The invariant is that every result remains traceable, replayable, and erasable, and no unverified item is marked complete.
Frequently asked questions
Can Shopify customer passwords migrate with the profile?
Customer CSV cannot move encrypted passwords from another store. Use invitation, activation, or secure reset for the selected account model, isolate rehearsal email, explain the process, and never handle plaintext passwords.
Can a customer with only an email be imported?
It can be handled under the current template and business rules, but purpose, consent, and duplication still need proof. An address without reliable identity or lawful purpose should not be imported or subscribed merely to increase list size.
Can old Total Spent and Total Orders values be written into Shopify?
Customer CSV does not turn old-platform totals into native Shopify order history. Where history matters, migrate order relationships or use a warehouse or read-only archive, and make the source visible to service and analytics.
How do we avoid duplicate customers after migration?
Keep a stable source-ID-to-Shopify-GID map, use normalized email and phone for conflict detection, resolve guest/registered and cross-system overlap first, and use a replayable upsert or batch method.
When must customer migration stop?
Stop when consent is inflated, identity is overwritten incorrectly, personal data is exposed, critical order or subscription links break, open privacy requests are missed, or rollback cannot execute. Pause affected batches and marketing, repair, and reconcile again.