diff --git a/docs/start/migration/customers/overview.mdx b/docs/start/migration/customers/overview.mdx new file mode 100644 index 000000000..fa26784e6 --- /dev/null +++ b/docs/start/migration/customers/overview.mdx @@ -0,0 +1,313 @@ +# Transferring Your Customers to BigCommerce + +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. + +## Create a Customer + +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 +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com" +} +``` + +For complete API documentation, see [Create Customers API Reference](/docs/rest-management/customers#create-customers). + +## API Rate Limits + +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 + +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" + }, + { + "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 +} +``` + + + + +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: + +- Password Management +- Customer Groups +- Customer Addresses +- Channels + +Let's cover each option in detail. + +### Password Management + +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. + +#### Preferred: No password (password reset required) + +Create customers without passwords and send password reset emails after migration: + +```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. + +#### Alternative: Set password during creation + + + 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. + + +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 + +Customer groups allow you to organize customers and control product visibility, pricing, and checkout options. Each customer can belong to only one group. + +**Key points for migration:** + +- 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 + +**Example Customer with customer group assignment payload:** + +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com", + "customer_group_id": 1 +} +``` + +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. + +### Customer Addresses + +Customer addresses can be included during customer creation. Each address has specific required fields that must be provided. + +**Required fields for addresses:** + +- `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 + +**Example Customer with minimal address payload:** + +```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" + } + ] +} +``` + +### 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 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 Customer with channel assignment and minimal payload:** + +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane@example.com", + "channel_ids": [1, 2] +} +``` + +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: + +- A temporary password (with forced reset) +- Assignment to customer group 1 +- A minimal address (required fields only) +- Assignment to channels 1 and 2 + +```json +{ + "first_name": "Jane", + "last_name": "Doe", + "email": "jane.doe@example.com", + "customer_group_id": 1, + "addresses": [ + { + "address1": "123 Main St", + "city": "San Francisco", + "country_code": "US", + "first_name": "Jane", + "last_name": "Doe", + "postal_code": "94105", + "state_or_province": "California" + } + ], + "authentication": { + "force_password_reset": true, + "new_password": "string123" + }, + "channel_ids": [1, 2] +} +``` + +## Additional Resources + +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) diff --git a/docs/start/migration/4_errors.md b/docs/start/migration/error-handling.mdx similarity index 100% rename from docs/start/migration/4_errors.md rename to docs/start/migration/error-handling.mdx diff --git a/docs/start/migration/overview.mdx b/docs/start/migration/overview.mdx index df76cbf9b..0382ae104 100644 --- 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. + + +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? -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 - -Data migration is complex and impacts your entire store setup. You should plan for it early in your project timeline to prevent setbacks. + + 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 +### 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. - -Category and brand IDs are not accessible by name, so create and cache a mapping schema to guarantee your catalog is properly configured. - +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 b/docs/start/migration/products/1-2_setup.md similarity index 100% rename from docs/start/migration/1-2_setup.md rename to docs/start/migration/products/1-2_setup.md diff --git a/docs/start/migration/3_testing.md b/docs/start/migration/products/3_testing.md similarity index 100% rename from docs/start/migration/3_testing.md rename to docs/start/migration/products/3_testing.md diff --git a/docs/start/migration/5_migrate.md b/docs/start/migration/products/5_migrate.md similarity index 100% rename from docs/start/migration/5_migrate.md rename to docs/start/migration/products/5_migrate.md diff --git a/docs/start/migration/6_delta.md b/docs/start/migration/products/6_delta.md similarity index 100% rename from docs/start/migration/6_delta.md rename to docs/start/migration/products/6_delta.md diff --git a/docs/start/migration/products/overview.mdx b/docs/start/migration/products/overview.mdx new file mode 100644 index 000000000..df76cbf9b --- /dev/null +++ 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 + + +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.