# Order Migration Documentation: Magento 2 to Shopify

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

## 1. Process Overview

The order migration is designed as a multi-stage, high-integrity process that captures not only the core order but also its history, payment details, and tracking information.

| Step | Action | Description |
| :--- | :--- | :--- |
| **1** | **Scan** | The command `migrate:orders` scans the Magento `sales_order` table. |
| **2** | **Queue** | Each order ID is dispatched to the `ProcessOrderMigration` job. |
| **3** | **Extract** | The job fetches the order with all relationships: Items, Addresses, Payment, Status History, Taxes, UTM Data, Invoices, and Tracking (including Oallocate). |
| **4** | **Transform** | `DetailedOrderTransformer` converts complex Magento structures into a Shopify-compatible JSON payload. |
| **5** | **Push** | `ShopifyService` creates the order in Shopify using the Admin API. |
| **6** | **Record** | Success/Failure is logged in the `order_migration_logs` table, and the full payload is saved to a dedicated log file for auditing. |

---

## 2. Core Order Mapping Table

### Header & Financial Data

| Magento Field (Source) | Shopify Field (Destination) | Transformation / Mapping Logic |
| :--- | :--- | :--- |
| `increment_id` | `name` (Shopify Order #) | Direct Migration |
| `customer_email` | `email` | Used for linking order to customer |
| `created_at` | `created_at` | Preserves original order timestamp |
| `state` / `status` | `financial_status` | `canceled`, `closed` → `voided`; `complete`, `processing`, `shipped` → `paid` |
| `state` / `status` | `fulfillment_status` | `complete`, `shipped` → `fulfilled`; `partial_shipped` → `partial`; else → `unfulfilled` |
| `grand_total` | `total_price` | Direct Migration |
| `subtotal` | `subtotal_price` | Direct Migration |
| `tax_amount` | `total_tax` | Direct Migration |
| `discount_amount` | `total_discounts` | Abs value of the discount |
| `customer_note` | `note` | Included at the top of the Order Note |

### Line Items Mapping

| Magento Field | Shopify Field | Logic |
| :--- | :--- | :--- |
| `name` | `title` | Product name in order |
| `sku` | `sku` | Used to link to Shopify Product via `ProductMapping` |
| `price` | `price` | Unit price at time of order |
| `qty_ordered` | `quantity` | Direct Migration |
| `tax_amount` | `taxable` | Boolean based on if tax was charged |
| `discount_amount` | `total_discount` | Per-item discount |

---

## 3. Advanced Data Capture

### Order Notes (History)
To preserve the "story" of the order, all Magento status history comments are concatenated into the Shopify **Order Note**.
- Format: `[Date] Comment (Status: X | Visible: Y)`
- Chronological Order: Latest updates appear first.
- Includes: Internal comments and customer notes.

### Tracking & AWB Details
The migration captures tracking information from two sources:
1.  **Magento Native Tracks**: Carrier and Tracking Number from `sales_flat_shipment_track`.
2.  **Oallocate Table**: Captures specialized courier details like AWB Number, Internal AWB, and Live Status.
*These are appended to the Order Note and stored in JSON metafields for searchability.*

### Payment Metafields
| Key | Logic |
| :--- | :--- |
| `payment_method` | Original Magento payment code (e.g., `razorpay`, `cashondelivery`) |
| `payment_gateway` | Normalized name (e.g., `Razorpay`, `Breeze`, `Cash on Delivery`) |
| `payment_transaction_id` | Extracted from invoice comments or payment transaction records |
| `payment_order_id` | Specific IDs for Razorpay or Breeze orders extracted from comments |

---

## 4. Metafields Migration Table

| Namespace | Key | Source Field | Description |
| :--- | :--- | :--- | :--- |
| `custom` | `magento_order_id` | `entity_id` | Internal Magento Database ID |
| `custom` | `magento_increment_id` | `increment_id` | Magento Order Number |
| `custom` | `magento_order_status` | `status` | Original Magento Status badge |
| `custom` | `checkout_gst_name` | `checkout_gst_name` | GST Billing Name |
| `custom` | `checkout_gst_number` | `checkout_gst_number`| GST Registration Number |
| `custom` | `utm_data` | `utm_report` | full UTM tracking parameters (JSON) |
| `custom` | `awb_details_json` | `oallocations` | Bulk tracking data (JSON) |

---

## 5. Technical Logic Notes

### Linking to Products
The script uses the `product_mappings` table to find the correct `shopify_variant_id`. If a SKU is found in the order but not in the mapping table, the item is still migrated as a **Custom Line Item** so the order totals remain correct.

### Inventory Protection
- `send_receipt` and `send_fulfillment_receipt` are set to **false** to ensure customers do not receive spam emails during migration.
- `inventory_behavior` can be set (usually `bypass`) to ensure migration does not interfere with live stock levels.

### GST & Referrer Capture
If GST details (`checkout_gst_name`/`number`) or a `referrer_url` are present in Magento, they are automatically stored as Order Metafields in Shopify to preserve tax and marketing data.

---

*End of Document*