DEVDOCS-6478 - Create Order Migrations guides

docs/start/migration/orders/complexity.mdx

@@ -0,0 +1,132 @@
+---
+title: Order Complexity Considerations
+description: Explore the key factors affecting order migration complexity in BigCommerce, such as products, customers, and order-level details, with actionable strategies for handling diverse scenarios during migration.
+keywords: order complexity, order migration, products, customers, order management, migration strategy, BigCommerce
+---
+# Complexity Considerations
+
+While order migration can be considered as a strictly “move information from here to here” sort of operation, there are factors that result in higher or lower levels of complexity that will change the ideal strategy used in migration planning.
+
+The content in this page outlines various considerations that go into planning against complexity for your migration strategy. During the preparation phase, you can refer back to the tables and flowcharts in this document to help build a clear understanding of the steps necessary to ensure a successful migration.
+
+While this stage isn’t explicitly necessary, it does help to mitigate potential pain-points in the migration process as a whole.
+
+## Products
+
+If your catalog is primarily simple products, the process only requires selection of products by `product_id`, while catalogs with primarily variable or modified products will require both `product_id` and some identification of the variants, modifiers, and possibly other data points to properly build up the order data. Here’s a breakdown of relevant factors to consider with regard to products:
+
+| Factor | Data | Use Case Example |
+| :---- | :---- | :---- |
+| Simple Products | `product_id` | Product with only one available ‘type’ |
+| Products with variants only | `product_id`, and `variant_id` or `product_options` array | Product with colors or sizes `variant_id` |
+| Products with modifiers only | `product_id` and `product_options` array | Product with custom text or other factors unaffected by inventory. |
+| Products with both | `product_id`, `product_options` array, and optionally `variant_id`.  | Product with color selections and  custom text |
+
+<Callout type="info">  
+While the table above indicates the use of `variant_id` for products with any variants, it can be helpful to split variant selections up in the `product_options` array for clarity in selections made.
+
+This splitting is reflected in the flowchart below, but it isn’t strictly necessary.  
+</Callout>
+
+As these features occur on a product-to-product basis, your migration code should account for each possible case that affects your catalog. Ideally you should aim for the minimal implementation that accomplishes your catalog’s needs, but a simple flow-chart for product handling at any complexity follows:
+
+```mermaid  
+flowchart LR  
+    B[Get<br />Product]  
+    B --> C[Add<br /> ID & Name]  
+    C --> D{Variants?}  
+    D -->|No| F{Modifiers?}  
+    D -->|Single| G[Add<br />Variant ID] --> F  
+    D -->|Multiple| H[Add<br />Options] --> F  
+
+    F -->|No| J[Output]  
+    F -->|Yes| I[Add<br />Options] --> J  
+
+    J --> K{More?}  
+    K -->|Yes| B  
+    K -->|No| M[Complete]  
+```
+
+More information on this will be explored when we cover the fields related to the [Create an Order](/docs/rest-management/orders#create-an-order) endpoint.
+
+<Callout type="info">  
+Older products no longer listed in your catalog can still be included in your customers’ order history as necessary, but it requires the use of the custom product workflow, which will be outlined when we cover fields.  
+</Callout>
+
+## Customers
+
+Customer complexity may be introduced in a few ways, but the primary sources are in address and contact data. Specifically, if billing and shipping information differ, separate objects will need to be built to manage the addresses when building an order’s total object data, but if they are the same a deep copy of one into the other will suffice.
+
+Likewise, if an order includes multiple separate shipping addresses, the array for shipping addresses will contain an address object for each. For older orders that have been completely fulfilled, this is less likely to impact your workflow, but outstanding shipping will require some consideration.
+
+Complexity considerations for customers are outlined here:
+
+| Factor | Data | Use Case Example |
+| :---- | :---- | :---- |
+| Guest customers | omit `customer_id` field | Customer does not log in, or does not have an account, before or during checkout. |
+| Billing address matches shipping address | `billing_address` | Customer ships and bills to a single address, usually attached to an account. |
+| Billing address differs from shipping address | `billing_address` and `shipping_addresses` fields | Customer shipping to PO Box or to alternate residence/office. |
+| Multiple shipping addresses | `shipping_addresses` array | Customer ordering for multiple locations at once. |
+| Consignments | `consignments.pickups` array | Customer picking up whole orders ‘in store’. |
+
+<Callout type="info">  
+If the `consignments` object is included in order data, both `shipping_addresses` and `products` must be excluded. This is a restriction on order processing preventing ‘pick up’ and ‘delivery’ from occurring on the same order.  
+</Callout>
+
+Just as with products, customer order data may be mixed complexity. As a result, either a pre-migration analysis or an adaptive order workflow should be implemented to capture the full scope of your project. While the latter is more effective, the former can help establish the scope of the adaptive workflow ahead of time and decrease complexity overall.
+
+```mermaid  
+flowchart LR  
+    B{Has<br />`customer_id`} -->|No| C[Add Billing<br />Address]  
+    B -->|Yes| D[Add ID] --> C
+
+    C --> E{Has<br />Consignments}  
+    E -->|No| F[Add<br />Products]  
+    E -->|Yes| G[Add<br />Consignments] --> H[Complete]  
+    F --> I --> H  
+    subgraph I[Shipping Addresses]  
+        I1{Has Addresses?} -->|No| I2[End]  
+        I1 -->|Yes| I3[Add to Array] --> I1  
+    end
+
+    click F "#products"  
+```
+
+## Order-level
+
+Once customer-specific and product-specific considerations are handled, some order-level issues may arise that increase complexity. For example, orders may have discounts applied that are no longer valid or haven’t been configured within BigCommerce. Alternatively, a specific order might have an order status that is no longer valid for any number of reasons.
+
+There are too many possible causes for order-level complexity to lay them out, but the following table gives several examples of fields that exist, the context they apply, and a use-case example for each.
+
+| Factor | Data | Use Case Example |
+| :---- | :---- | :---- |
+| Order-level Fees | `fees` array | Shipping to Colorado and applying the Retail Delivery Fee for record-keeping. |
+| Customer Comments | `customer_message` field | Customers leave notes for shipping instructions or to thank your team. |
+| Staff Notes | `staff_notes` field | Your team leaves comments about order management. Not visible to customers. |
+| Gift Wrapping | `*_wrapping_cost` fields | Customers request gift wrapping, if you provide the option. |
+| Incomplete Payments | varies | Customers using offline payment methods or customized split payment systems. |
+
+## FAQs
+
+1. **What should I do if my catalog contains custom products not present in BigCommerce?**  
+   Use the custom product workflow, providing name, quantity, and price fields. See [Orders API - Create an Order](/docs/rest-management/orders#create-an-order) for details.
+2. **Can I migrate guest orders?**  
+   Yes. Omit the `customer_id` field for guest orders; use billing address/contact info for identification.
+3. **How do I handle orders with multiple shipping addresses?**  
+   Include an array under `shipping_addresses` with each address object. Ensure each address is mapped correctly.
+4. **What if my order includes both consignments (pickups) and deliveries?**  
+   Consignments and shipping addresses/products are mutually exclusive in a single order. Split such orders into separate records if both are needed.
+5. **How do I map product variants and modifiers in order data?**  
+   Include the relevant `product_id`, `variant_id`, and/or `product_options` array per product line item.
+6. **What fields are required for a minimal order migration?**  
+   At minimum: `external_source`, `external_order_id`, `status_id`, `date_created`, `billing_address`, `products`. See [Prepare Data](/docs/start/migration/orders/prepare-data) for more.
+7. **How do I ensure order data is not duplicated?**  
+   Use unique identifiers and check for existing orders before creation. Log all migrated order IDs for auditing.
+
+## Resources
+
+- [Orders API - Create an Order](/docs/rest-management/orders#create-an-order)
+- [Catalog API](/docs/rest-catalog)
+- [Order Management (Help Center)](https://support.bigcommerce.com/s/article/Guide-to-Order-Management)
+- [Payments API](/docs/rest-payments)
+- [API Best Practices](/docs/start/best-practices)

docs/start/migration/orders/migration-phase.mdx

@@ -0,0 +1,112 @@
+---
+title: Migration Phase
+description: Detailed instructions for executing the migration phase of order data to BigCommerce, including testing, full migration, delta migration, verification, and troubleshooting steps for a successful order transfer.
+keywords: order migration, migration phase, testing, delta migration, BigCommerce, order verification, data transfer
+---
+# Migration Phase
+
+Just as with products, your order migration should include at minimum: testing, initial migration, delta migration. The initial testing process and delta migration will look very similar to those steps in the products migration process, so you can refer back to them as needed. (Load Complete Data)[/docs/start/migration/products/complete-migration] and (Go Live and Delta Migration)[/docs/start/migration/products/delta-migration].
+
+There are some callouts specific to the order migration process, which will be addressed here, but otherwise, use your best judgement when considering how to manage your own work.
+
+## Load test data
+
+This step is essential in verifying you’ve appropriately mapped your order data from your previous data source (ERP, CRM, or other) to BigCommerce. When you’ve finished your data preparation step we encourage you to do the following in loading test data:
+
+- **Ensure ALL order data include the `external_source` field with the value `M-MIG` before beginning.**  
+- Turn off your order notifications in both your sandbox and production environments  
+- Prepare a representative sample from your existing data. Sanitize this data for testing, in case of errors or overlap.  
+- Load the sanitized data into your sandbox environment, logging any errors encountered.  
+- Verify the sample data loaded without issue.  
+- Identify inconsistencies with sample data and revise your mapping strategy accordingly.
+
+Once you’ve successfully migrated your initial test data, move on to the full migration step.
+
+## Migrate your full order history
+
+Once you've successfully tested your order migration process, verified mappings, and gained confidence in your approach, you're ready to proceed with loading your complete order dataset into BigCommerce.
+
+### Pre-Migration checklist
+
+* Remove all extraneous data (test orders, unnecessary attributes) from your dataset  
+* ⚠️ Disable or turn OFF any third-party applications that might automatically ingest product data  
+* Verify the API rate limits for your plan level  
+* Scheduling your migration during off-peak hours, if possible, to minimize potential platform congestion
+
+<Callout type="info">  
+If you are still accepting orders via your previous platform, define a clear “cut-off” time to avoid missing late changes.  
+</Callout>  
+<Callout type="info">  
+When performing large-scale migrations, it is essential to use structures that ensure data is not duplicated. Use unique order identifiers to check if an order exists before retrying an API call to create it.  
+</Callout>
+
+### During migration
+
+* Actively monitor for status error codes and implement your error handling protocols  
+* Track progress through logging to ensure you transfer all products correctly.  
+* Maintain a separate record of any failed transfers for later remediation
+
+### Post-Migration verification
+
+* Compare order counts between your source platform and BigCommerce  
+* Spot-check a representative sample of orders across your complete history  
+* Check that you have transferred complex orders (refer to complexity considerations) correctly.  
+* Test order visibility by using customer impersonation to ensure appropriate account linkage.
+
+### Next Steps
+
+* Once order data is successfully transferred, proceed with migrating design data (theme, etc.) if desired.  
+* Document your migration process thoroughly for future reference or troubleshooting  
+* Consider implementing a synchronization strategy or data freeze if you'll be operating multiple platforms simultaneously during transition
+
+### Estimated time to transfer
+
+The following table provides approximations of migration times for various order history sizes. These estimates are based on platform limits and assumed order complexity. If you have particularly complex orders, your results will vary from these provisions.
+
+Based on this information and the guidance provided above, plan your migration with enough time allotted to prevent issues.
+
+| Resources | Estimated time (store with no live integrations) |
+| :---- | :---- |
+| > 5,000 | Around 30 minutes |
+| > 40,000 | Around  7 hours |
+| > 300,000 | Around 23 hours |
+| > 500,000+ | Recommended to work with our dedicated data migration services team on data processing |
+
+<Callout type="info">
+The information in the table above is based on the platform limits, assuming scaling complexity with order history size. For information on platform limits, see our documentation on [Best Practices](/docs/start/best-practices) and [API Limits](/docs/start/best-practices/api-rate-limits).
+</Callout>
+
+## Delta migration
+
+This step is only required if you are still receiving orders in a live environment during your migration. As with the testing phase, this step has a few callouts to be aware of. We recommend the following steps to ensure a successful delta migration with the fewest errors.
+
+- Before initial migration, take a snapshot of your current order status.  
+- Before performing delta migration, take your store down for maintenance if possible.  
+- Compare snapshot data to newest data, and only update orders for which there is new data to report.  
+- If you took your store down for maintenance for delta migration, reactivate it once you have finished.  
+- Verify data successfully transferred via spot check.
+
+It’s important to note that your order delta migration will vary in size based on your store’s activity. As such, you should plan enough time to account for the full scope of the project, following the table above.
+
+## FAQs
+
+1. **How do I prepare test data for order migration?**  
+   Prepare a representative and sanitized sample of orders, ensure required fields are present, and load into your sandbox for validation.
+2. **How can I avoid duplicate orders during migration?**  
+   Use unique order identifiers and check for existing orders before retrying API calls.
+3. **What should I do if my migration fails or is interrupted?**  
+   Log all migrated order IDs and failed records. Use logs to identify and correct only affected orders.
+4. **How do I handle delta migrations if new orders are placed during migration?**  
+   Take a snapshot before initial migration, compare to new data after, and only migrate newly placed or updated orders.
+5. **How can I verify a successful migration?**  
+   Compare source and destination order counts, spot-check complex orders, and validate correct customer and product linkages.
+6. **What are platform limits for order migration?**  
+   See [API Rate Limits](/docs/start/best-practices/api-rate-limits) for details. For very large datasets, contact [Data Migration Services](https://www.bigcommerce.com/services/launch/#data-migration-services).
+
+## Resources
+
+- [API Best Practices | BigCommerce Dev Center](/docs/start/best-practices)
+- [API Rate Limits](/docs/start/best-practices/api-rate-limits)
+- [Data Migration Services](https://www.bigcommerce.com/services/launch/#data-migration-services)
+- [Orders API Reference](/docs/rest-management/orders)
+