# Customer Migration Documentation: Magento 2 to Shopify

This document outlines the complete process, data mapping, and technical steps for migrating customers from Magento 2 to Shopify using the `migrate:customers` artisan command.

## 1. Process Overview

The migration is a high-performance, asynchronous process designed to handle large customer databases.

| Step | Action | Description |
| :--- | :--- | :--- |
| **1** | **Scan** | The command `migrate:customers` scans the Magento `customer_entity` table. |
| **2** | **Dispatch** | Each customer is queued as a background job `ProcessCustomerMigration`. |
| **3** | **Fetch** | The job retrieves the full Magento customer profile, including addresses and EAV attributes. |
| **4** | **Transform** | The `CustomerTransformer` service maps Magento fields to Shopify's GraphQL Schema. |
| **5** | **Push** | The `ShopifyService` sends the payload to Shopify via the `customerCreate` mutation. |
| **6** | **Log** | Success or failure is recorded in the `customer_migration_logs` table. |

---

## 2. Data Mapping Table

### Core Profile Data

| Magento Field (Source) | Shopify Field (Destination) | Transformation Logic |
| :--- | :--- | :--- |
| `firstname` | `firstName` | Case Correction (Title Case) |
| `lastname` | `lastName` | Case Correction (Title Case) |
| `email` | `email` | Direct Migration |
| `newsletter_subscriber.status` | `emailMarketingConsent` | Status 1 → `SUBSCRIBED`, Status 3 → `UNSUBSCRIBED` |
| `entity_id` | `tags` | Added "Magento" tag for easy filtering |
| `phone_number` (EAV) | `phone` | Cleaned and prefixed with `+91` (E.164 standard) |

### Address Mapping

| Magento Address Field | Shopify Address Field | Transformation Logic |
| :--- | :--- | :--- |
| `street` (Line 1) | `address1` | Trimmed to 255 chars |
| `street` (Line 2+) | `address2` | Concatenated lines after the first |
| `city` | `city` | Title Case |
| `region` | `province` | Title Case |
| `postcode` | `zip` | Direct Migration |
| `country_id` | `country` | ISO 2-letter code (e.g., IN, US) |
| `telephone` | `phone` | Direct Migration |
| `default_billing` / `shipping` | `default` | Flags the primary address in Shopify |

---

## 3. Metafields (Custom Shared Data)

All custom Magento data is stored in the `custom` namespace in Shopify for future reference.

| Shopify Metafield Key | Magento Source | Data Type |
| :--- | :--- | :--- |
| `magento_customer_id` | `entity_id` | `single_line_text_field` |
| `magento_created_date` | `created_at` | `date_time` |
| `dob` | `dob` | `date` |
| `gender` | `gender` (ID mapped) | `single_line_text_field` |
| `customer_group` | `customer_group.code` | `single_line_text_field` |
| `website` | `store_website.name` | `single_line_text_field` |
| `store_view` | `store.name` | `single_line_text_field` |
| `spouse_name` | `spouse` (EAV) | `single_line_text_field` |
| `anniversary` | `anniversary` (EAV) | `date` |
| `phone_number` | `phone_number` (Raw) | `single_line_text_field` |

---

## 4. Technical Implementation Notes

### Phone Number Cleaning Logic
To comply with Shopify's strict E.164 requirements:
1. Remove all non-numeric characters.
2. Strip leading `0` or `91` prefixes.
3. Validate that exactly 10 digits remain.
4. Prepend `+91` (Standard for India).

### Address Deduplication
The script generates a unique hash based on address lines, zip, and city. If a customer has identical addresses (common in Magento imports), only the first primary occurrence is migrated to Shopify to prevent redundancy.

### Status Tracking
Monitor the migration using the `customer_migration_logs` table:
```sql
SELECT status, count(*) FROM customer_migration_logs GROUP BY status;
```

---

*End of Document*