From 88d6a6da654c18d9491c37863cb504f9c5bf4b38 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Mon, 22 Sep 2025 13:03:05 -0500 Subject: [PATCH 01/16] Initial Overview Update Commit --- .../migration/{ => catalog}/1-2_setup.md | 0 .../migration/{ => catalog}/3_testing.md | 0 .../start/migration/{ => catalog}/4_errors.md | 0 .../migration/{ => catalog}/5_migrate.md | 0 docs/start/migration/{ => catalog}/6_delta.md | 0 docs/start/migration/catalog/overview.mdx | 52 ++++++++++++ docs/start/migration/overview.mdx | 84 +++++++++++-------- 7 files changed, 103 insertions(+), 33 deletions(-) rename docs/start/migration/{ => catalog}/1-2_setup.md (100%) rename docs/start/migration/{ => catalog}/3_testing.md (100%) rename docs/start/migration/{ => catalog}/4_errors.md (100%) rename docs/start/migration/{ => catalog}/5_migrate.md (100%) rename docs/start/migration/{ => catalog}/6_delta.md (100%) create mode 100644 docs/start/migration/catalog/overview.mdx diff --git a/docs/start/migration/1-2_setup.md b/docs/start/migration/catalog/1-2_setup.md similarity index 100% rename from docs/start/migration/1-2_setup.md rename to docs/start/migration/catalog/1-2_setup.md diff --git a/docs/start/migration/3_testing.md b/docs/start/migration/catalog/3_testing.md similarity index 100% rename from docs/start/migration/3_testing.md rename to docs/start/migration/catalog/3_testing.md diff --git a/docs/start/migration/4_errors.md b/docs/start/migration/catalog/4_errors.md similarity index 100% rename from docs/start/migration/4_errors.md rename to docs/start/migration/catalog/4_errors.md diff --git a/docs/start/migration/5_migrate.md b/docs/start/migration/catalog/5_migrate.md similarity index 100% rename from docs/start/migration/5_migrate.md rename to docs/start/migration/catalog/5_migrate.md diff --git a/docs/start/migration/6_delta.md b/docs/start/migration/catalog/6_delta.md similarity index 100% rename from docs/start/migration/6_delta.md rename to docs/start/migration/catalog/6_delta.md diff --git a/docs/start/migration/catalog/overview.mdx b/docs/start/migration/catalog/overview.mdx new file mode 100644 index 000000000..df76cbf9b --- /dev/null +++ b/docs/start/migration/catalog/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 + + +Data migration is complex and impacts your entire store setup. You should plan for it early in your project timeline to prevent setbacks. + + +### 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. + + +Category and brand IDs are not accessible by name, so create and cache a mapping schema to guarantee your catalog is properly configured. + + +## 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. diff --git a/docs/start/migration/overview.mdx b/docs/start/migration/overview.mdx index df76cbf9b..63798c06f 100644 --- a/docs/start/migration/overview.mdx +++ b/docs/start/migration/overview.mdx @@ -1,52 +1,70 @@ --- -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. +Now that you've made the decision to move your store to BigCommerce, it's time to start the logistics of transferring your catalog. Recognizing that there is no single solution that will fit every business, we support several ways to migrate your data, ranging from our data migration apps to completely managed transfers through BigCommerce's Data Migration Services team. -## Why focus on data migration? +Factors such as ease of use, number of SKUs, orders and sales history, and custom product fields are key considerations to take into account before selecting a migration method. -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. +### Available Methods -## Migration workflow pages +| | Data Migration app (free, with limitations*) | CSV Import (free) | Managed Transfer | BigCommerce Apps | +|--------------|----------------------------------------------|-------------------|------------------|------------------| +| Products | ✔ | ✔ | ✔ | N/A | +| Categories | ✔ | ✔ | ✔ | N/A | +| Customers** | ✔ | ✔ | ✔ | N/A | +| Orders | ✔ | X | ✔ | N/A | +| Reviews | X | X | X | [Product Review Importer & Exporter app (free)](https://www.bigcommerce.com/apps/product-review-importer/) | -- [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) +*The free version of our data migration app is limited to a combined total of 1,000 products, orders, and customers.
+**Passwords cannot be migrated for PCI compliance -## Getting started +#### DATA MIGRATION APPS - -Data migration is complex and impacts your entire store setup. You should plan for it early in your project timeline to prevent setbacks. - +Our data migration apps allow you to migrate your catalog data resources (products, categories, customers, orders) into your new BigCommerce store from the following platforms: -### Recommended preparatory tasks +- [Shopify](https://www.bigcommerce.com/apps/data-migration-services-shopify/) +- [Volusion](https://www.bigcommerce.com/apps/data-migration-volusion/) +- [WooCommerce](https://www.bigcommerce.com/apps/data-migration-services-woocommerce/) +- [Magento](https://www.bigcommerce.com/apps/data-migration-services-magento/) +- [Zen Cart](https://www.bigcommerce.com/apps/data-migration-services-zen-cart/) +- [Yahoo](https://www.bigcommerce.com/apps/data-migration-services-yahoo/) -- **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. +The demo versions of these apps are available in the App Marketplace, and are free to use for the first 1,000 resources. After this limit has been reached, there is a fee for transferring additional resources using the full app. Use the in-app contact form for more information. -- **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. +Ideal for those new to BigCommerce, the data migration apps should be the first step in relaunching your store on the BigCommerce platform. As the apps make a copy of your current store's catalog, they do not affect your live store. While each app has its own requirements specific to the hosting platform, they all require that: -- **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. +- Your current store is accessible from the Internet +- You have full administrative access to your current store's control panel - -Category and brand IDs are not accessible by name, so create and cache a mapping schema to guarantee your catalog is properly configured. - +Any data stored in plug-ins or extensions will most likely not be included in the transfer, and would need to be added manually or by CSV import afterwards. If you have any data you need to preserve inside your BigCommerce store, +we suggest [exporting it](https://support.bigcommerce.com/s/article/Backing-Up-Your-Store) to create a backup copy before starting the transfer. + +Basic customer details, such as name, email address, phone number, and physical addresses will be transferred. +However, since passwords can't be exported from most platforms for PCI compliance, customers are transferred with a +feature flag that requires them to reset their password the next time they attempt to log in. + +#### CSV IMPORT -## Additional resources +As an alternative, you can import your [products](https://support.bigcommerce.com/s/article/Legacy-Import-Export-Overview) and [customers](https://support.bigcommerce.com/s/article/Importing-Exporting-Customers/#import) into your BigCommerce store by using a CSV file. Keep in mind that you will +likely need to reformat your source CSV file so that it can be imported successfully into your BigCommerce store. Spreadsheet programs +such as Excel or Google Sheets are necessary in order to edit CSV files. For stores with less than 10,000 SKUs, +we recommend using one of our data migration apps for migrating your products, and then using a CSV import to clean up your product data. -For more technical details and API documentation, see: +#### MANAGED DATA MIGRATION -- [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) +If you don't feel comfortable migrating your store's data using the app or CSV file, consider using a managed data transfer through BigCommerce's [Data Migration Services](https://www.bigcommerce.com/services/launch/) team. They will work directly with you to ensure that your data is securely migrated to your satisfaction, tailoring their services to match your business needs. The team is highly experienced in working with large catalogs with SKUs on more than 50 ecommerce platforms. +They are also able to handle custom migration requests to best meet the needs of your store's architecture. [Contact us](https://www.bigcommerce.com/request-quote/) to request a quote. -By following these recommendations and the linked migration workflow pages, you can manage your BigCommerce product migration with greater confidence and fewer disruptions. +#### API + +Developers can use our Catalog, Orders, and Customers API to add and modify products, orders, and customer data directly. See our [API Documentation](https://developer.bigcommerce.com/api-docs) on the Dev Center for more detailed information and examples. + + + **How do I ensure that imported historical orders aren't counted as new orders or GMV?**
+ When migrating orders from a previous platform, which involves [creating new orders via API](https://developer.bigcommerce.com/docs/rest-management/orders#create-an-order), + use M-MIG in the external_source field to exclude these orders from affecting your store's [trailing 12-month sales volume](https://support.bigcommerce.com/s/article/Pricing). + These orders do not deduct product stock and will bypass quantity requirements. + From c421cf7b4c98a83e5112c0e2897fe71073473996 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 23 Sep 2025 09:48:30 -0500 Subject: [PATCH 02/16] move error handling to root migration folder --- docs/start/migration/{catalog/4_errors.md => error-handling.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/start/migration/{catalog/4_errors.md => error-handling.md} (100%) diff --git a/docs/start/migration/catalog/4_errors.md b/docs/start/migration/error-handling.md similarity index 100% rename from docs/start/migration/catalog/4_errors.md rename to docs/start/migration/error-handling.md From 32f3315dae9723e0b6a0925c2890449b5517a777 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 23 Sep 2025 10:29:27 -0500 Subject: [PATCH 03/16] udpate overview and rename catelog folder to products --- docs/start/migration/overview.mdx | 82 ++++++++----------- .../{catalog => products}/1-2_setup.md | 0 .../{catalog => products}/3_testing.md | 0 .../{catalog => products}/5_migrate.md | 0 .../{catalog => products}/6_delta.md | 0 .../{catalog => products}/overview.mdx | 0 6 files changed, 35 insertions(+), 47 deletions(-) rename docs/start/migration/{catalog => products}/1-2_setup.md (100%) rename docs/start/migration/{catalog => products}/3_testing.md (100%) rename docs/start/migration/{catalog => products}/5_migrate.md (100%) rename docs/start/migration/{catalog => products}/6_delta.md (100%) rename docs/start/migration/{catalog => products}/overview.mdx (100%) diff --git a/docs/start/migration/overview.mdx b/docs/start/migration/overview.mdx index 63798c06f..da4baf801 100644 --- a/docs/start/migration/overview.mdx +++ b/docs/start/migration/overview.mdx @@ -4,67 +4,55 @@ title: Transferring Your Catalog to BigCommerce # Catalog data migration: Best practices and process overview -Now that you've made the decision to move your store to BigCommerce, it's time to start the logistics of transferring your catalog. Recognizing that there is no single solution that will fit every business, we support several ways to migrate your data, ranging from our data migration apps to completely managed transfers through BigCommerce's Data Migration Services team. +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. -Factors such as ease of use, number of SKUs, orders and sales history, and custom product fields are key considerations to take into account before selecting a migration method. +There are several methods to migrating your catalog data into BigCommerce. These sections focus on using our APIs. For other methods like CSV import, +Data Migration Apps, and Managed Transfer Services, please refer to our knowledge base article, [Transferring Your Catalog to BigCommerce](https://support.bigcommerce.com/s/article/Transferring-Your-Catalog-to-BigCommerce?language=en_US). -### Available Methods +## Why focus on data migration? -| | Data Migration app (free, with limitations*) | CSV Import (free) | Managed Transfer | BigCommerce Apps | -|--------------|----------------------------------------------|-------------------|------------------|------------------| -| Products | ✔ | ✔ | ✔ | N/A | -| Categories | ✔ | ✔ | ✔ | N/A | -| Customers** | ✔ | ✔ | ✔ | N/A | -| Orders | ✔ | X | ✔ | N/A | -| Reviews | X | X | X | [Product Review Importer & Exporter app (free)](https://www.bigcommerce.com/apps/product-review-importer/) | +Catalog data migration affects products, categories, customers, 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. -*The free version of our data migration app is limited to a combined total of 1,000 products, orders, and customers.
-**Passwords cannot be migrated for PCI compliance +## Migration order -#### DATA MIGRATION APPS +We recommend migrating your data in the following order: -Our data migration apps allow you to migrate your catalog data resources (products, categories, customers, orders) into your new BigCommerce store from the following platforms: +- Categories +- Brands +- Products +- Customers +- B2B Properties +- Orders -- [Shopify](https://www.bigcommerce.com/apps/data-migration-services-shopify/) -- [Volusion](https://www.bigcommerce.com/apps/data-migration-volusion/) -- [WooCommerce](https://www.bigcommerce.com/apps/data-migration-services-woocommerce/) -- [Magento](https://www.bigcommerce.com/apps/data-migration-services-magento/) -- [Zen Cart](https://www.bigcommerce.com/apps/data-migration-services-zen-cart/) -- [Yahoo](https://www.bigcommerce.com/apps/data-migration-services-yahoo/) +## Getting started -The demo versions of these apps are available in the App Marketplace, and are free to use for the first 1,000 resources. After this limit has been reached, there is a fee for transferring additional resources using the full app. Use the in-app contact form for more information. - -Ideal for those new to BigCommerce, the data migration apps should be the first step in relaunching your store on the BigCommerce platform. As the apps make a copy of your current store's catalog, they do not affect your live store. While each app has its own requirements specific to the hosting platform, they all require that: - -- Your current store is accessible from the Internet -- You have full administrative access to your current store's control panel + + Data migration is complex and impacts your entire store setup. You should plan + for it early in your project timeline to prevent setbacks. + -Any data stored in plug-ins or extensions will most likely not be included in the transfer, and would need to be added manually or by CSV import afterwards. If you have any data you need to preserve inside your BigCommerce store, -we suggest [exporting it](https://support.bigcommerce.com/s/article/Backing-Up-Your-Store) to create a backup copy before starting the transfer. +### Recommended preparatory tasks -Basic customer details, such as name, email address, phone number, and physical addresses will be transferred. -However, since passwords can't be exported from most platforms for PCI compliance, customers are transferred with a -feature flag that requires them to reset their password the next time they attempt to log in. +{/* TODO: List of preparatory tasks */} -#### CSV IMPORT +- **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. -As an alternative, you can import your [products](https://support.bigcommerce.com/s/article/Legacy-Import-Export-Overview) and [customers](https://support.bigcommerce.com/s/article/Importing-Exporting-Customers/#import) into your BigCommerce store by using a CSV file. Keep in mind that you will -likely need to reformat your source CSV file so that it can be imported successfully into your BigCommerce store. Spreadsheet programs -such as Excel or Google Sheets are necessary in order to edit CSV files. For stores with less than 10,000 SKUs, -we recommend using one of our data migration apps for migrating your products, and then using a CSV import to clean up your product data. +- **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. -#### MANAGED DATA MIGRATION +- **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. -If you don't feel comfortable migrating your store's data using the app or CSV file, consider using a managed data transfer through BigCommerce's [Data Migration Services](https://www.bigcommerce.com/services/launch/) team. They will work directly with you to ensure that your data is securely migrated to your satisfaction, tailoring their services to match your business needs. The team is highly experienced in working with large catalogs with SKUs on more than 50 ecommerce platforms. -They are also able to handle custom migration requests to best meet the needs of your store's architecture. [Contact us](https://www.bigcommerce.com/request-quote/) to request a quote. +## Additional resources -#### API +For more technical details and API documentation, see: -Developers can use our Catalog, Orders, and Customers API to add and modify products, orders, and customer data directly. See our [API Documentation](https://developer.bigcommerce.com/api-docs) on the Dev Center for more detailed information and examples. +- [Catalog API Reference](/docs/rest-catalog) +- [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) +- [Transferring Your Catalog to BigCommerce KB article](https://support.bigcommerce.com/s/article/Transferring-Your-Catalog-to-BigCommerce?language=en_US) - - **How do I ensure that imported historical orders aren't counted as new orders or GMV?**
- When migrating orders from a previous platform, which involves [creating new orders via API](https://developer.bigcommerce.com/docs/rest-management/orders#create-an-order), - use M-MIG in the external_source field to exclude these orders from affecting your store's [trailing 12-month sales volume](https://support.bigcommerce.com/s/article/Pricing). - These orders do not deduct product stock and will bypass quantity requirements. - +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/catalog/1-2_setup.md b/docs/start/migration/products/1-2_setup.md similarity index 100% rename from docs/start/migration/catalog/1-2_setup.md rename to docs/start/migration/products/1-2_setup.md diff --git a/docs/start/migration/catalog/3_testing.md b/docs/start/migration/products/3_testing.md similarity index 100% rename from docs/start/migration/catalog/3_testing.md rename to docs/start/migration/products/3_testing.md diff --git a/docs/start/migration/catalog/5_migrate.md b/docs/start/migration/products/5_migrate.md similarity index 100% rename from docs/start/migration/catalog/5_migrate.md rename to docs/start/migration/products/5_migrate.md diff --git a/docs/start/migration/catalog/6_delta.md b/docs/start/migration/products/6_delta.md similarity index 100% rename from docs/start/migration/catalog/6_delta.md rename to docs/start/migration/products/6_delta.md diff --git a/docs/start/migration/catalog/overview.mdx b/docs/start/migration/products/overview.mdx similarity index 100% rename from docs/start/migration/catalog/overview.mdx rename to docs/start/migration/products/overview.mdx From 4f725f9b295de623d2c275e1ed1b38d240fe85e5 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 23 Sep 2025 12:09:55 -0500 Subject: [PATCH 04/16] finalized initial draft of migration overview --- docs/start/migration/customers/overview.mdx | 0 docs/start/migration/overview.mdx | 35 ++++++++++++++------- 2 files changed, 24 insertions(+), 11 deletions(-) create mode 100644 docs/start/migration/customers/overview.mdx diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx new file mode 100644 index 000000000..e69de29bb diff --git a/docs/start/migration/overview.mdx b/docs/start/migration/overview.mdx index da4baf801..70e3ba076 100644 --- a/docs/start/migration/overview.mdx +++ b/docs/start/migration/overview.mdx @@ -6,16 +6,21 @@ title: Transferring Your Catalog to BigCommerce 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. These sections focus on using our APIs. For other methods like CSV import, -Data Migration Apps, and Managed Transfer Services, please refer to our knowledge base article, [Transferring Your Catalog to BigCommerce](https://support.bigcommerce.com/s/article/Transferring-Your-Catalog-to-BigCommerce?language=en_US). +There are several methods to migrating your catalog data into BigCommerce. This migration guide focuses on using our REST and/or GraphQL APIs. + + +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. + ## Why focus on data migration? -Catalog data migration affects products, categories, customers, orders, and overall customer experience. +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. + We recommend migrating your data in the following order: - Categories @@ -32,18 +37,26 @@ We recommend migrating your data in the following order: for it early in your project timeline to prevent setbacks. -### Recommended preparatory tasks +### Create API Tokens + +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: + +| Scope | Modify | +| --------------------- | :----: | +| Customers | X | +| Orders | X | +| Products | X | +| Storefront API tokens | X | -{/* TODO: List of preparatory tasks */} +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. -- **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 more information on API accounts see our [Guide to API accounts](https://developer.bigcommerce.com/docs/start/authentication/api-accounts) documentation. -- **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. +### Prepare store for migration -- **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. +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 From 2a4688c150a6ff37e26e4e5fe282db1919c6674f Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 23 Sep 2025 20:27:38 -0500 Subject: [PATCH 05/16] finalized initial draft of customer migration --- docs/start/migration/customers/overview.mdx | 185 ++++++++++++++++++++ docs/start/migration/overview.mdx | 4 +- 2 files changed, 188 insertions(+), 1 deletion(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index e69de29bb..50af11a34 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -0,0 +1,185 @@ +# 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": "jane@example.com", + "authentication": { + "force_reset": true, + "new_password": "TempPass123" + } +} +``` + +Setting `force_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. + + + Use CSV import only if you need to bulk-assign groups in one action. + Otherwise, use the API. + + +#### 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. + +#### Custom form fields + +If your store uses custom form fields (at signup or for addresses), make sure they are created in the destination store **before migration**. Then, you can map values to those fields when creating or updating customers. + +Example (with a custom field value on creation): + +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com", + "custom_fields": [ + { + "field_id": 1, + "field_value": "VIP" + } + ] +} +``` + +### 2. Migrate customer data + +#### Rate limits + + + Create up to 10 customers per `POST /v3/customers` call; implement backoff + using the rate-limit headers. + + +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 + + + Tip: You can assign `store_credit_amounts` when creating customers. If + omitted, you can add it later with PUT /customers/{id}. + + +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": "jane@example.com" +} +``` + +Example request body: + +```json +{ + "email": "jane.doe@example.com", + "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/overview.mdx b/docs/start/migration/overview.mdx index 70e3ba076..0382ae104 100644 --- a/docs/start/migration/overview.mdx +++ b/docs/start/migration/overview.mdx @@ -47,7 +47,9 @@ Before getting started, make sure you have a Store-Level API token with the foll | Customers | X | | Orders | X | | Products | X | -| Storefront API tokens | X | +| Storefront API tokens* | X | + + ***Storefront API tokens** are only necessary if you plan to migrate B2B properties. 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. From 1f76fefc735a6a014ef381e220735df577320c5b Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 23 Sep 2025 20:32:55 -0500 Subject: [PATCH 06/16] formatting fix --- docs/start/migration/customers/overview.mdx | 22 +-------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index 50af11a34..499512998 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -57,26 +57,6 @@ Setting `force_reset: true` ensures customers must update their password at firs - Channels must be created in the control panel before migration. - Customers without a channel assignment default to global access. -#### Custom form fields - -If your store uses custom form fields (at signup or for addresses), make sure they are created in the destination store **before migration**. Then, you can map values to those fields when creating or updating customers. - -Example (with a custom field value on creation): - -```json -{ - "first_name": "Jane", - "last_name": "Doe", - "email": "jane@example.com", - "custom_fields": [ - { - "field_id": 1, - "field_value": "VIP" - } - ] -} -``` - ### 2. Migrate customer data #### Rate limits @@ -96,7 +76,7 @@ BigCommerce APIs are subject to rate limits. Always design your migration to: Tip: You can assign `store_credit_amounts` when creating customers. If - omitted, you can add it later with PUT /customers/{id}. + omitted, you can add it later with `PUT /customers/{id}`. minimum required fields: From e8c7e0db93319b790b211e387ebfa8b973a57a34 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 23 Sep 2025 20:35:02 -0500 Subject: [PATCH 07/16] fix password reset example --- docs/start/migration/customers/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index 499512998..20e128f1b 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -32,13 +32,13 @@ Options: "last_name": "Doe", "email": "jane@example.com", "authentication": { - "force_reset": true, - "new_password": "TempPass123" + "force_password_reset": true, + "new_password": "string123" } } ``` -Setting `force_reset: true` ensures customers must update their password at first login. +Setting `force_password_reset: true` ensures customers must update their password at first login. #### Customer groups From 4174a68e6a54220b4c6f1ef43733f0a2607b0b8d Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Mon, 29 Sep 2025 15:25:04 -0400 Subject: [PATCH 08/16] add segments and update to customer groups --- docs/start/migration/customers/overview.mdx | 34 ++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index 20e128f1b..84fae480d 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -40,12 +40,44 @@ Options: Setting `force_password_reset: true` ensures customers must update their password at first login. +#### Customer Segments + + + Customer segments are only available to merchants with an Enterprise plan. If + you do not have an Enterprise plan, skip this section and move on to Customer + Groups. + + +We recommend creating [customer segments](https://developer.bigcommerce.com/docs/store-operations/customer-segmentation/user-guide) in place of customer groups for more flexibility. + +- Segments can be created and managed via the API only and must be created before migration. +- If you choose to use customer segments, then you don't need to include the `customer_group_id` field when creating customers. +- See our [Customer Segments API documentation](https://developer.bigcommerce.com/docs/rest-management/customers#customer-segments) for details. + +**Advantages** +- Robust +- Stable against category changes + +**Disadvantages** +- Cannot be managed via the control panel UI; all work requires a custom solution, a developer, or an app + #### Customer groups + + If you are using customer segments, skip this section and move on to Channels + / Multi-Storefront. + + - 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. +- Customers can be assigned to groups during creation (`customer_group_id`) or afterward via API. - Each customer can belong to only one group. +**Advantages** +- Simple, quick, straightforward + +**Disadvantages** +- New categories don't automatically get visibility rules applied, so complex grouping becomes difficult as catalogs evolve + Use CSV import only if you need to bulk-assign groups in one action. Otherwise, use the API. From 8f199a1f83132c62fe5c5e9786714476663efa1b Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Tue, 30 Sep 2025 08:35:17 -0400 Subject: [PATCH 09/16] rename error-handling.md to error-handling.mdx --- docs/start/migration/{error-handling.md => error-handling.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/start/migration/{error-handling.md => error-handling.mdx} (100%) diff --git a/docs/start/migration/error-handling.md b/docs/start/migration/error-handling.mdx similarity index 100% rename from docs/start/migration/error-handling.md rename to docs/start/migration/error-handling.mdx From c7d9a338c0aff7475992bfbdd93ee3c9f87837b9 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Fri, 10 Oct 2025 14:59:16 -0400 Subject: [PATCH 10/16] fix: document structure based on james q feedback --- docs/start/migration/customers/overview.mdx | 347 +++++++++++++------- 1 file changed, 227 insertions(+), 120 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index 84fae480d..d11bf908f 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -2,196 +2,303 @@ ## 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. +Customer information can be transferred to a BigCommerce store via the [REST Management API](/docs/rest-management/customers). This guide outlines the recommended process for migrating customers. -We recommend migrating customers in the following order: +**API endpoint:** [`POST /customers`](/docs/rest-management/customers#create-customers) -1. Prepare prerequisites -2. Create customers -3. Validate and finalize +Customer creation, at minimum, requires only 3 fields: -## Migration Steps +- `first_name` +- `last_name` +- `email` -### 1. Preparing for customer migration +**Minimal request body:** -Before you begin, decide on the following: +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com" +} +``` -#### Passwords +## API Rate Limits for Customer Migration -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) +You can create up to 10 customers per `POST /v3/customers` call and implement retry logic +using the rate-limit headers. -Options: +### Best Practices for API Rate Limits -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: +1. **Batch Requests**: Create up to 10 customers per API call to maximize efficiency +2. **Monitor Rate Limits**: Check `X-Rate-Limit-Requests-Left` before making requests +3. **Implement Retry Logic**: Use exponential backoff when receiving `429` responses +4. **Distribute Load**: Spread requests over time rather than making them in bursts + +### Example: Batch Customer Creation + + + ```json -{ - "first_name": "Jane", - "last_name": "Doe", - "email": "jane@example.com", - "authentication": { - "force_password_reset": true, - "new_password": "string123" +[ + { + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com" + }, + { + "first_name": "John", + "last_name": "Smith", + "email": "john@example.com" + }, + { + "first_name": "Alice", + "last_name": "Johnson", + "email": "alice@example.com" + }, + { + "first_name": "Bob", + "last_name": "Williams", + "email": "bob@example.com" + }, + { + "first_name": "Carol", + "last_name": "Brown", + "email": "carol@example.com" + }, + { + "first_name": "David", + "last_name": "Jones", + "email": "david@example.com" + }, + { + "first_name": "Emma", + "last_name": "Garcia", + "email": "emma@example.com" + }, + { + "first_name": "Frank", + "last_name": "Miller", + "email": "frank@example.com" + }, + { + "first_name": "Grace", + "last_name": "Davis", + "email": "grace@example.com" + }, + { + "first_name": "Henry", + "last_name": "Rodriguez", + "email": "henry@example.com" } +] +``` + + + + +```javascript +async function createCustomers(customerData) { + const response = await fetch( + 'https://api.bigcommerce.com/stores/{store_hash}/v3/customers', + { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'X-Auth-Token': 'your_access_token', + }, + body: JSON.stringify(customerData), + } + ) + + // Handle rate limiting + if (response.status === 429) { + const resetTime = response.headers.get('X-Rate-Limit-Time-Reset-Ms') + const waitTime = resetTime ? parseInt(resetTime) : 1000 + + console.log(`Rate limited. Waiting ${waitTime}ms before retry`) + await new Promise((resolve) => setTimeout(resolve, waitTime)) + + // Retry the request + return createCustomers(customerData) + } + + return response } ``` -Setting `force_password_reset: true` ensures customers must update their password at first login. +For complete API documentation, see [Create Customers](https://developer.bigcommerce.com/docs/rest-management/customers#create-customers) in the BigCommerce API reference. -#### Customer Segments + + - - Customer segments are only available to merchants with an Enterprise plan. If - you do not have an Enterprise plan, skip this section and move on to Customer - Groups. - +## Customer Creation Options -We recommend creating [customer segments](https://developer.bigcommerce.com/docs/store-operations/customer-segmentation/user-guide) in place of customer groups for more flexibility. +There are options to consider when creating customers based on your needs. In this section we cover: -- Segments can be created and managed via the API only and must be created before migration. -- If you choose to use customer segments, then you don't need to include the `customer_group_id` field when creating customers. -- See our [Customer Segments API documentation](https://developer.bigcommerce.com/docs/rest-management/customers#customer-segments) for details. +- Password Management +- Customer Groups +- Customer Addresses +- Multi-Storefront (Channels) -**Advantages** -- Robust -- Stable against category changes +Let's cover each option in detail. -**Disadvantages** -- Cannot be managed via the control panel UI; all work requires a custom solution, a developer, or an app +### Password Management -#### Customer groups +Due to PCI compliance, you cannot migrate passwords. This means you can either create customers without passwords and send password reset emails after migration or set a password during creation. - - If you are using customer segments, skip this section and move on to Channels - / Multi-Storefront. - +#### Preferred: No password (password reset required) -- 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. +Create customers without passwords and send password reset emails after migration: -**Advantages** -- Simple, quick, straightforward +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com" +} +``` + +After migration, send a password reset email to each customer. You can use your preferred email service to send a generic email to all users with instructions to reset their password using the storefront login page. -**Disadvantages** -- New categories don't automatically get visibility rules applied, so complex grouping becomes difficult as catalogs evolve +#### Alternative: Set password during creation - - Use CSV import only if you need to bulk-assign groups in one action. - Otherwise, use the API. + + If you set a password during creation, ensure each user gets a unique + password. Using the same password for multiple accounts creates a security + risk. We recommend sending password reset emails instead of setting passwords + during creation. -#### Channels / Multi-Storefront +To set a temporary password, include the `authentication` object with `force_password_reset: true` and `new_password`: + +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com", + "authentication": { + "force_password_reset": true, + "new_password": "string123" + } +} +``` + +### Customer Groups -- 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. +Customer groups allow you to organize customers and control product visibility, pricing, and checkout options. Each customer can belong to only one group. -### 2. Migrate customer data +**Key points for migration:** -#### Rate limits +- Customer groups must be created in the control panel before migration (cannot be created via API) +- Assign customers to groups using the `customer_group_id` field during creation +- Groups control which products customers can see and purchase - - Create up to 10 customers per `POST /v3/customers` call; implement backoff - using the rate-limit headers. - +**Example with customer group assignment:** + +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com", + "customer_group_id": 1 +} +``` -BigCommerce APIs are subject to rate limits. Always design your migration to: +For detailed information about creating and managing customer groups, see [Customer Groups](https://support.bigcommerce.com/s/article/Customer-Groups?language=en_US#how) in the BigCommerce support documentation. -- Batch requests where possible -- Implement retries with exponential backoff -- Monitor headers: `X-Rate-Limit-Remaining` +### Customer Addresses -#### Create customers +Customer addresses can be included during customer creation. Each address has specific required fields that must be provided. - - Tip: You can assign `store_credit_amounts` when creating customers. If - omitted, you can add it later with `PUT /customers/{id}`. - +**Required fields for addresses:** -minimum required fields: +- `address1` - Street address line 1 +- `city` - City name +- `country_code` - Two-letter country code (e.g., "US", "CA", "GB") +- `first_name` - First name for the address +- `last_name` - Last name for the address +- `postal_code` - ZIP/postal code +- `state_or_province` - State or province name -- `first_name` -- `last_name` -- `email` +**Example with minimal address:** + +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com", + "addresses": [ + { + "address1": "123 Main St", + "city": "San Francisco", + "country_code": "US", + "first_name": "Jane", + "last_name": "Doe", + "postal_code": "94105", + "state_or_province": "California" + } + ] +} +``` -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. +### Multi-Storefront (Channels) -Example minimal request body: +**Requirements:** + +- Channels must be created in the control panel before migration +- Customers without a channel assignment default to global access + +**Example with minimal payload:** ```json { "first_name": "Jane", "last_name": "Doe", - "email": "jane@example.com" + "email": "jane@example.com", + "channel_ids": [1, 2] } ``` -Example request body: +## Complete Example + +Here is a comprehensive example showing a customer created with: + +- A temporary password (with forced reset) +- Assignment to customer group 1 +- A minimal address (required fields only) +- Assignment to channels 1 and 2 ```json { - "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", - "company": "Acme Corp", - "phone": "512-555-1234", - "notes": "VIP customer", - "customer_group_id": 2, + "email": "jane.doe@example.com", + "customer_group_id": 1, "addresses": [ { - "address1": "Addr 1", - "address2": "", - "address_type": "residential", + "address1": "123 Main St", "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" - } - ] + "first_name": "Jane", + "last_name": "Doe", + "postal_code": "94105", + "state_or_province": "California" } ], "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" - } - ] + "channel_ids": [1, 2] } ``` -### 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 +## 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) +- [API best practices](/docs/start/best-practices/api-rate-limits#best-practices) - [Data migration services](https://www.bigcommerce.com/services/launch/#data-migration-services) From 45244919b7089e2b04caa7bcbbdf862522462925 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Fri, 10 Oct 2025 15:11:19 -0400 Subject: [PATCH 11/16] fix: remove initial header as it was redundant --- docs/start/migration/customers/overview.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index d11bf908f..a93f97e19 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -1,7 +1,5 @@ # Transferring Your Customers to BigCommerce -## Customer data migration: Best practices and process overview - Customer information can be transferred to a BigCommerce store via the [REST Management API](/docs/rest-management/customers). This guide outlines the recommended process for migrating customers. **API endpoint:** [`POST /customers`](/docs/rest-management/customers#create-customers) From abd1c3a0b158dd79ca5cd9996b85e628123c221a Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Fri, 10 Oct 2025 15:34:28 -0400 Subject: [PATCH 12/16] fix: add additional information for channels --- docs/start/migration/customers/overview.mdx | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index a93f97e19..a43ff546c 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -137,7 +137,7 @@ There are options to consider when creating customers based on your needs. In th - Password Management - Customer Groups - Customer Addresses -- Multi-Storefront (Channels) +- Channels Let's cover each option in detail. @@ -192,7 +192,7 @@ Customer groups allow you to organize customers and control product visibility, - Assign customers to groups using the `customer_group_id` field during creation - Groups control which products customers can see and purchase -**Example with customer group assignment:** +**Example Customer with customer group assignment payload:** ```json { @@ -219,7 +219,7 @@ Customer addresses can be included during customer creation. Each address has sp - `postal_code` - ZIP/postal code - `state_or_province` - State or province name -**Example with minimal address:** +**Example Customer with minimal address payload:** ```json { @@ -240,14 +240,16 @@ Customer addresses can be included during customer creation. Each address has sp } ``` -### Multi-Storefront (Channels) +### Channels + +Channels allow you to create different storefronts or customer experiences (multi-storefront, headless commerce, mobile apps, marketplaces, etc.). You can assign customers to specific channels to control which storefront they can access. **Requirements:** -- Channels must be created in the control panel before migration +- Channels must be created before migration (can be created via the [Rest Management API](/docs/rest-management/channels#create-a-channel) or control panel) - Customers without a channel assignment default to global access -**Example with minimal payload:** +**Example Customer with channel assignment and minimal payload:** ```json { @@ -258,7 +260,9 @@ Customer addresses can be included during customer creation. Each address has sp } ``` -## Complete Example +For detailed information about creating and managing channels, see [Getting Started with Channels](https://support.bigcommerce.com/s/article/Getting-Started-Channels?language=en_US) in the BigCommerce support documentation. + +## Customer Creation Example Payload Here is a comprehensive example showing a customer created with: @@ -299,4 +303,5 @@ For more technical details and API documentation, see: - [Create Customer API Reference](/docs/rest-management/customers#create-customers) - [API rate limits](/docs/start/best-practices/api-rate-limits) - [API best practices](/docs/start/best-practices/api-rate-limits#best-practices) +- [Getting Started with Channels](https://support.bigcommerce.com/s/article/Getting-Started-Channels?language=en_US) - [Data migration services](https://www.bigcommerce.com/services/launch/#data-migration-services) From d526c8aeaed0683f3dd3d9bd8dd97251c27fa454 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Fri, 10 Oct 2025 15:37:13 -0400 Subject: [PATCH 13/16] fix: added clarity to optional fields --- docs/start/migration/customers/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index a43ff546c..20aff8926 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -132,7 +132,7 @@ For complete API documentation, see [Create Customers](https://developer.bigcomm ## Customer Creation Options -There are options to consider when creating customers based on your needs. In this section we cover: +In addition to the required fields (`first_name`, `last_name`, `email`), there are optional fields you can include when creating customers based on your needs: - Password Management - Customer Groups From 6eeff1d5f5c4005bfc6ae0fd2c40e3ea31047865 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Fri, 10 Oct 2025 15:45:29 -0400 Subject: [PATCH 14/16] fix: minor introduction fix --- docs/start/migration/customers/overview.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index 20aff8926..53be9aa44 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -1,8 +1,8 @@ # Transferring Your Customers to BigCommerce -Customer information can be transferred to a BigCommerce store via the [REST Management API](/docs/rest-management/customers). This guide outlines the recommended process for migrating customers. +By the end of this guide, you'll understand how to migrate customers to BigCommerce using the [REST Management API](/docs/rest-management/customers). You'll learn how to create customers with the minimum required fields, handle API rate limits, and optionally include passwords, customer groups, addresses, and channel assignments. -**API endpoint:** [`POST /customers`](/docs/rest-management/customers#create-customers) +**API endpoint:** `POST https://api.bigcommerce.com/stores/{store_hash}/v3/customers` Customer creation, at minimum, requires only 3 fields: @@ -20,6 +20,9 @@ Customer creation, at minimum, requires only 3 fields: } ``` +For complete API documentation, see [Create Customers API Reference](/docs/rest-management/customers#create-customers). + + ## API Rate Limits for Customer Migration You can create up to 10 customers per `POST /v3/customers` call and implement retry logic From 00c8a766667f6b2c9c6941b3d248ebb91a23cccf Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Fri, 10 Oct 2025 16:03:45 -0400 Subject: [PATCH 15/16] add additional context to end of api rate limits section --- docs/start/migration/customers/overview.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index 53be9aa44..aa52b9716 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -22,7 +22,6 @@ Customer creation, at minimum, requires only 3 fields: For complete API documentation, see [Create Customers API Reference](/docs/rest-management/customers#create-customers). - ## API Rate Limits for Customer Migration You can create up to 10 customers per `POST /v3/customers` call and implement retry logic @@ -128,11 +127,14 @@ async function createCustomers(customerData) { } ``` -For complete API documentation, see [Create Customers](https://developer.bigcommerce.com/docs/rest-management/customers#create-customers) in the BigCommerce API reference. - +For detailed information about rate limits and best practices, see: + +- [API rate limits](/docs/start/best-practices/api-rate-limits) +- [API best practices](/docs/start/best-practices/api-rate-limits#best-practices) + ## Customer Creation Options In addition to the required fields (`first_name`, `last_name`, `email`), there are optional fields you can include when creating customers based on your needs: From a88687e645eaabd416c97776b8f12110c07ece84 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Mon, 13 Oct 2025 14:10:25 -0400 Subject: [PATCH 16/16] updates per james q comments --- docs/start/migration/customers/overview.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx index aa52b9716..fa26784e6 100644 --- a/docs/start/migration/customers/overview.mdx +++ b/docs/start/migration/customers/overview.mdx @@ -2,14 +2,16 @@ By the end of this guide, you'll understand how to migrate customers to BigCommerce using the [REST Management API](/docs/rest-management/customers). You'll learn how to create customers with the minimum required fields, handle API rate limits, and optionally include passwords, customer groups, addresses, and channel assignments. -**API endpoint:** `POST https://api.bigcommerce.com/stores/{store_hash}/v3/customers` +## Create a Customer -Customer creation, at minimum, requires only 3 fields: +To create a customer, send a POST request to the `/v3/customers` API endpoint. This request, at minimum, requires 3 fields: - `first_name` - `last_name` - `email` +**API endpoint:** `POST https://api.bigcommerce.com/stores/{store_hash}/v3/customers` + **Minimal request body:** ```json @@ -22,10 +24,9 @@ Customer creation, at minimum, requires only 3 fields: For complete API documentation, see [Create Customers API Reference](/docs/rest-management/customers#create-customers). -## API Rate Limits for Customer Migration +## API Rate Limits -You can create up to 10 customers per `POST /v3/customers` call and implement retry logic -using the rate-limit headers. +Each `POST request to the /v3/customers` endpoint allows you to create up to 10 customers and implement retry logic using the rate-limit headers. ### Best Practices for API Rate Limits