bigcommerce · chris-nowicki · Sep 22, 2025 · Sep 23, 2025 · Sep 23, 2025 · Sep 23, 2025
diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx
@@ -0,0 +1,165 @@
+# Transferring Your Customers to BigCommerce
+
+## Customer data migration: Best practices and process overview
+
+Customer information can be transferred to a BigCommerce store via the API. This guide outlines the recommended process for migrating customers with minimal dependencies on CSV import.
+
+We recommend migrating customers in the following order:
+
+1. Prepare prerequisites
+2. Create customers
+3. Validate and finalize
+
+## Migration Steps
+
+### 1. Preparing for customer migration
+
+Before you begin, decide on the following:
+
+#### Passwords
+
+Passwords can be set via API using the `authentication` object when creating customers:
+[`POST /customers`](https://developer.bigcommerce.com/docs/rest-management/customers#create-customers)
+
+Options:
+
+1. **Preferred method**: Create customers without a password and notify them to reset using a password reset link.
+2. **Alternative**: Provide a password during creation by including the `authentication` object. Example:
+
+```json
+{
+	"first_name": "Jane",
+	"last_name": "Doe",
+	"email": "[email protected]",
+	"authentication": {
+		"force_password_reset": true,
+		"new_password": "string123"
+	}
+}
+```
+
+Setting `force_password_reset: true` ensures customers must update their password at first login.
+
+#### Customer groups
+
+- Customer groups must be created in the control panel before migration.
+- Customers can be assigned to groups during creation (customer_group_id) or afterward via API.
+- Each customer can belong to only one group.
+
+<Callout type='info'>
+	Use CSV import only if you need to bulk-assign groups in one action.
+	Otherwise, use the API.
+</Callout>
+
+#### Channels / Multi-Storefront
+
+- Decide whether customers have global or channel-specific access.
+- Channels must be created in the control panel before migration.
+- Customers without a channel assignment default to global access.
+
+### 2. Migrate customer data
+
+#### Rate limits
+
+<Callout type='info'>
+	Create up to 10 customers per `POST /v3/customers` call; implement backoff
+	using the rate-limit headers.
+</Callout>
+
+BigCommerce APIs are subject to rate limits. Always design your migration to:
+
+- Batch requests where possible
+- Implement retries with exponential backoff
+- Monitor headers: `X-Rate-Limit-Remaining`
+
+#### Create customers
+
+<Callout>
+	Tip: You can assign `store_credit_amounts` when creating customers. If
+	omitted, you can add it later with `PUT /customers/{id}`.
+</Callout>
+
+minimum required fields:
+
+- `first_name`
+- `last_name`
+- `email`
+
+Use the [`POST /customers`](https://developer.bigcommerce.com/docs/rest-management/customers#create-customers) endpoint to create customers. Include all required fields and any optional fields needed.
+
+Example minimal request body:
+
+```json
+{
+	"first_name": "Jane",
+	"last_name": "Doe",
+	"email": "[email protected]"
+}
+```
+
+Example request body:
+
+```json
+{
+	"email": "[email protected]",
+	"first_name": "Jane",
+	"last_name": "Doe",
+	"company": "Acme Corp",
+	"phone": "512-555-1234",
+	"notes": "VIP customer",
+	"customer_group_id": 2,
+	"addresses": [
+		{
+			"address1": "Addr 1",
+			"address2": "",
+			"address_type": "residential",
+			"city": "San Francisco",
+			"company": "History",
+			"country_code": "US",
+			"first_name": "Ronald",
+			"last_name": "Swimmer",
+			"phone": "707070707",
+			"postal_code": "33333",
+			"state_or_province": "California",
+			"form_fields": [
+				{
+					"name": "Delivery Instructions",
+					"value": "Leave at front desk"
+				}
+			]
+		}
+	],
+	"authentication": {
+		"force_password_reset": true,
+		"new_password": "string123"
+	},
+	"store_credit_amounts": [
+		{
+			"amount": 43.15
+		}
+	],
+	"channel_ids": [1, 2],
+	"form_fields": [
+		{
+			"name": "Delivery Instructions",
+			"value": "Leave at front desk"
+		}
+	]
+}
+```
+
+### 3. Post-migration tasks
+
+- Trigger password reset emails (if customers were created without passwords).
+- Verify login across channels.
+- Spot-check customer group assignments and store credit.
+- Confirm that custom fields and preferences are correctly associated.
+
+## Additional resources
+
+For more technical details and API documentation, see:
+
+- [Create Customer API Reference](/docs/rest-management/customers#create-customers)
+- [API best practices](/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)
diff --git a/docs/start/migration/4_errors.md → docs/start/migration/error-handling.md b/docs/start/migration/4_errors.md → docs/start/migration/error-handling.md
diff --git a/docs/start/migration/overview.mdx b/docs/start/migration/overview.mdx
@@ -1,43 +1,64 @@
 ---
-title: Product data migration overview
+title: Transferring Your Catalog to BigCommerce
 ---
 
-# Product data migration: Best practices and process overview
+# Catalog data migration: Best practices and process overview
 
-Migrating product data is a foundational part of launching or replatforming an ecommerce store. This section provides practical guidance and best practices for migrating your product catalog into BigCommerce, focusing on accuracy, efficiency, and minimizing common migration errors.
+Migrating catalog data is a foundational part of launching or replatforming an ecommerce store. This section provides practical guidance and best practices for migrating your catalog into BigCommerce, focusing on accuracy, efficiency, and minimizing common migration errors.
+
+There are several methods to migrating your catalog data into BigCommerce. This migration guide focuses on using our REST and/or GraphQL APIs.
+
+<Callout type='info'>
+For other methods like CSV import, Data Migration Apps, and Managed Transfer Services, please refer to our [Transferring Your Catalog to BigCommerce](https://support.bigcommerce.com/s/article/Transferring-Your-Catalog-to-BigCommerce?language=en_US) knowledge base article.
+</Callout>
 
 ## Why focus on data migration?
 
-Product data migration affects core areas of your storefront, including product listings, search, inventory, pricing, and overall customer experience. Early planning and process validation help reduce the risk of errors and delays during launch. The following pages walk through the technical and operational steps of migration to support a smooth transition.
+Catalog data migration affects categories, brands, products, customers, B2B properties, orders, and overall customer experience.
+Early planning and process validation help reduce the risk of errors and delays during launch. The following pages walk through the technical and operational steps of migration using our APIs to support a smooth transition.
+
+## Migration order
+
+Some data types have dependencies that require a specific order. For example, products must be assigned to existing categories and brands, so categories and brands should be created first.
 
-## Migration workflow pages
+We recommend migrating your data in the following order:
 
-- [Prepare Your Migration Data](/docs/start/migration/prepare-data)
-- [Test a Limited Dataset](/docs/start/migration/test-data)
-- [Error Handling](/docs/start/migration/error-handling)
-- [Load Complete Data](/docs/start/migration/complete-migration)
-- [Go Live and Delta Migration](/docs/start/migration/delta-migration)
+- Categories
+- Brands
+- Products
+- Customers
+- B2B Properties
+- Orders
 
 ## Getting started
 
-<Callout type="info">
-Data migration is complex and impacts your entire store setup. You should plan for it early in your project timeline to prevent setbacks.
+<Callout type='info'>
+	Data migration is complex and impacts your entire store setup. You should plan
+	for it early in your project timeline to prevent setbacks.
 </Callout>
 
-### Recommended preparatory tasks
+### Create API Tokens
 
-- **Test your migration workflow early**  
-  Once you have defined your migration plan and scope, test your migration process in a non-production environment. Address any issues found during testing before moving to a full migration.
+For initial migration, it can be helpful to establish a single token with all the scopes required for a complete data transfer.
+Before getting started, make sure you have a Store-Level API token with the following scopes:
 
-- **Align store settings and source data**  
-  Before importing product data, configure your store’s [store settings](https://support.bigcommerce.com/s/article/Store-Settings) including product weight units, dimensions, currency, and timezone. Check that your source data matches these settings to avoid inconsistencies.
+| Scope                 | Modify |
+| --------------------- | :----: |
+| Customers             |   X    |
+| Orders                |   X    |
+| Products              |   X    |
+| Storefront API tokens* |   X    |
 
-- **Configure categories and brands in advance**  
-  Categories and brands must be created in BigCommerce before importing products. Category and brand assignments are done by numeric ID, not by name. Prepare a mapping between your source data and BigCommerce IDs to ensure products are assigned correctly. See the [Catalog API Reference](/docs/rest-catalog) for details.
+ ***Storefront API tokens** are only necessary if you plan to migrate B2B properties.
 
-<Callout type="info">
-Category and brand IDs are not accessible by name, so create and cache a mapping schema to guarantee your catalog is properly configured.
-</Callout>
+You can create and manage API tokens in your BigCommerce control panel under **Settings** > **API** > **Store-level API accounts**.
+Once there, select the "Create API account" button in the upper right hand corner.
+
+For more information on API accounts see our [Guide to API accounts](https://developer.bigcommerce.com/docs/start/authentication/api-accounts) documentation.
+
+### Prepare store for migration
+
+Before importing product data, configure your store's [store settings](https://support.bigcommerce.com/s/article/Store-Settings) including product weight units, dimensions, currency, and timezone. Check that your source data matches these settings to avoid inconsistencies.
 
 ## Additional resources
 
@@ -46,7 +67,7 @@ For more technical details and API documentation, see:
 - [Catalog API Reference](/docs/rest-catalog)
 - [API best practices](/docs/start/best-practices)
 - [API rate limits](/docs/start/best-practices/api-rate-limits)
-- [WebDAV file access](https://support.bigcommerce.com/s/article/File-Access-WebDAV)
 - [Data migration services](https://www.bigcommerce.com/services/launch/#data-migration-services)
+- [Transferring Your Catalog to BigCommerce KB article](https://support.bigcommerce.com/s/article/Transferring-Your-Catalog-to-BigCommerce?language=en_US)
 
-By following these recommendations and the linked migration workflow pages, you can manage your BigCommerce product migration with greater confidence and fewer disruptions.
+By following these recommendations and the linked migration workflow pages, you can manage your BigCommerce catalog migration with greater confidence and fewer disruptions.
diff --git a/docs/start/migration/1-2_setup.md → docs/start/migration/products/1-2_setup.md b/docs/start/migration/1-2_setup.md → docs/start/migration/products/1-2_setup.md
diff --git a/docs/start/migration/3_testing.md → docs/start/migration/products/3_testing.md b/docs/start/migration/3_testing.md → docs/start/migration/products/3_testing.md
diff --git a/docs/start/migration/5_migrate.md → docs/start/migration/products/5_migrate.md b/docs/start/migration/5_migrate.md → docs/start/migration/products/5_migrate.md
diff --git a/docs/start/migration/6_delta.md → docs/start/migration/products/6_delta.md b/docs/start/migration/6_delta.md → docs/start/migration/products/6_delta.md
diff --git a/docs/start/migration/products/overview.mdx b/docs/start/migration/products/overview.mdx
@@ -0,0 +1,52 @@
+---
+title: Product data migration overview
+---
+
+# Product data migration: Best practices and process overview
+
+Migrating product data is a foundational part of launching or replatforming an ecommerce store. This section provides practical guidance and best practices for migrating your product catalog into BigCommerce, focusing on accuracy, efficiency, and minimizing common migration errors.
+
+## Why focus on data migration?
+
+Product data migration affects core areas of your storefront, including product listings, search, inventory, pricing, and overall customer experience. Early planning and process validation help reduce the risk of errors and delays during launch. The following pages walk through the technical and operational steps of migration to support a smooth transition.
+
+## Migration workflow pages
+
+- [Prepare Your Migration Data](/docs/start/migration/prepare-data)
+- [Test a Limited Dataset](/docs/start/migration/test-data)
+- [Error Handling](/docs/start/migration/error-handling)
+- [Load Complete Data](/docs/start/migration/complete-migration)
+- [Go Live and Delta Migration](/docs/start/migration/delta-migration)
+
+## Getting started
+
+<Callout type="info">
+Data migration is complex and impacts your entire store setup. You should plan for it early in your project timeline to prevent setbacks.
+</Callout>
+
+### Recommended preparatory tasks
+
+- **Test your migration workflow early**  
+  Once you have defined your migration plan and scope, test your migration process in a non-production environment. Address any issues found during testing before moving to a full migration.
+
+- **Align store settings and source data**  
+  Before importing product data, configure your store’s [store settings](https://support.bigcommerce.com/s/article/Store-Settings) including product weight units, dimensions, currency, and timezone. Check that your source data matches these settings to avoid inconsistencies.
+
+- **Configure categories and brands in advance**  
+  Categories and brands must be created in BigCommerce before importing products. Category and brand assignments are done by numeric ID, not by name. Prepare a mapping between your source data and BigCommerce IDs to ensure products are assigned correctly. See the [Catalog API Reference](/docs/rest-catalog) for details.
+
+<Callout type="info">
+Category and brand IDs are not accessible by name, so create and cache a mapping schema to guarantee your catalog is properly configured.
+</Callout>
+
+## Additional resources
+
+For more technical details and API documentation, see:
+
+- [Catalog API Reference](/docs/rest-catalog)
+- [API best practices](/docs/start/best-practices)
+- [API rate limits](/docs/start/best-practices/api-rate-limits)
+- [WebDAV file access](https://support.bigcommerce.com/s/article/File-Access-WebDAV)
+- [Data migration services](https://www.bigcommerce.com/services/launch/#data-migration-services)
+
+By following these recommendations and the linked migration workflow pages, you can manage your BigCommerce product migration with greater confidence and fewer disruptions.