How to migrate your data to SCAYLE

For an established brand with shops in multiple countries, keeping your customer base during the move to SCAYLE is essential. To make sure these customers can keep buying from your shop without needing to register again, their data needs to be migrated. Also, you should migrate closed order data from your old e-commerce platform to SCAYLE, so customers can see their past orders in their My Account area.

Orders still being processed during the switch will be completed on the old platform. This means you'll need to repeat the order data migration process several times after the switch to SCAYLE, until all orders are transferred.

Introduction

Migrating to a new e-commerce platform like SCAYLE involves transferring existing data, more than just moving product details and customer profiles. It's also crucial to migrate order data. If customer data isn't migrated, your customers will have to register again, disrupting their experience. Not migrating order data means customers won't see their past purchases in their account area. This oversight can lead to customer dissatisfaction, lost sales, and potentially harm your brand's reputation.

Prerequisites

To fully grasp this tutorial, you should be familiar with the interrelationships among the Customers, Orders, Basket, and Product business objects in SCAYLE. Additionally, a basic understanding of how SCAYLE's Admin APIs function and the nature of source data from your legacy e-commerce system is beneficial.

Data Migration Process

In the following, we'll walk you through the essential steps for a successful data migration, highlighting how SCAYLE's features can support you in each phase. Remember, this is a simplified, high-level overview and should be customized to suit your specific requirements:\

In the event of any issues during the data migration process, follow these corrective steps:\

• Data removal: If a task fails, immediately remove any loaded data from SCAYLE. This action prevents the retention of any incorrect or incomplete data within the system.
• Data migration retry: After the removal of loaded data, reattempt the migration process. It may be necessary to repeat this process several times until successful data integration into SCAYLE is achieved.

By following these guidelines, you’ll maintain data integrity and ensure that only accurate and complete data is loaded into SCAYLE. This approach is key to a successful launch of your new shop(s) on the SCAYLE platform.

Understanding the Data Structure in SCAYLE for Migration

When migrating to SCAYLE, understanding the structure and relationships of various business objects is key. Here’s a detailed look at the data types you’ll be transitioning from your external systems:

The diagram illustrates the key relationships between business objects relevant for data migration in SCAYLE.

How to migrate customers to SCAYLE?

Migrate customers and their related data using SCAYLE's Admin API. The migration typically includes:\

• Customer personal data
• Addresses
• Passwords

This section guides you through the customer data migration process in SCAYLE.

Preparing for Customer Data Migration to SCAYLE

The process of migrating customer data to SCAYLE begins with extracting the relevant information from your old system. As part of this initial phase, which aligns with the broader data migration process, it's essential to cleanse legacy data by making strategic decisions about which customer accounts to transfer. Consider excluding:

• Inactive or dormant accounts.
• Accounts that have been closed.

Be mindful of compliance with regulations like GDPR or CCPA. Ensure that you migrate data necessary for legal compliance and responsibly archive or delete data that's not required.

Communication with your customers about this transition is also important. Inform them about the nature of the data migration, its implications, and how their data will be utilized in SCAYLE. Where applicable, provide them with options regarding their data.

After extracting the data from your legacy system, it needs to be transformed to align with SCAYLE's format. This step involves modifying data formats, types, and field names to ensure compatibility with SCAYLE’s system.

Creating a new customer

Before migrating sensitive details like passwords or addresses, the foundational step is transferring the customer's data. This process creates a customer profile within SCAYLE using personal data through the 'create new customer' endpoint of SCAYLE's Admin API. This step includes specifying whether a customer is an active (registered) user or a guest user.

In addition, you can add a reference key to create a relation between the customer in your system and their new profile in SCAYLE. Additionally, there's the option to categorize customers into groups, such as VIPs or employees, depending on your specific needs. The necessity for customer groups will vary based on your unique requirements. If you’re uncertain about the need for customer groups, we’re here to help – feel free to reach out for guidance on your specific situation.

Given that each source system has its unique structure for storing customer-related data, it's likely that you'll need to develop a logic to map this data to SCAYLE's format. Planning for this logic creation is a crucial component of the customer migration process.

Below is an illustrative example of how one customer's data might be migrated. Note that not all fields in this example are mandatory. For detailed information on required and optional data fields, please refer to our documentation.

Example payload to create a new customer:\

json

Copy

During the migration, you might encounter errors. SCAYLE’s comprehensive error codes provide detailed insights into any issues, complete with informative error messages. For more information on handling these, please refer to: SCAYLE Error Handling and Validations during the Migration Process.

Creating a new customer address

Once you've moved your customer data to SCAYLE, the next step is to add their known addresses. This is done using SCAYLE’s Create New Customer Address endpoint. You can add addresses using either the referenceKey assigned to each customer during the creation process, or by using the internal customer ID provided by SCAYLE when a customer is successfully created.

When creating an address, you'll need to include standard details such as the recipient's name, street, house number, zip code, city, and country code. You can also add extra information like ‘first floor’ or ‘c/o My Fashion Company’. You can also specify whether the address is primarily for shipping or billing by setting isDefault.billing or isDefault.shipping to true.

For shipping addresses, you might want to include collection point details. Most carriers offer various collection options like lockers or post offices. This information can be added in the collectionPoint field. Below is an example of how to create a new address for a previously migrated customer, using the same referenceKey.

Example payload for creating a new customer address:

json

Copy

During the migration of customer addresses, you may encounter some errors. Fortunately, SCAYLE’s error codes will guide you to the root of the problem with detailed error messages. For more insight on handling these errors, please refer to: SCAYLE Error Handling and Validations during the Migration Process.

Migrating passwords to SCAYLE

Before starting the password migration process, ensure that the corresponding customer profiles exist in SCAYLE. Password migration in SCAYLE can take different forms based on two crucial factors: whether the password is known in plain text or hashed, and whether the validation will be conducted internally by SCAYLE or requires the involvement of an external service. In the upcoming sections, we’ll delve into these different scenarios, highlighting the key differences and providing a detailed guide on how to successfully migrate your customers' passwords.

Case 1: Migrating Known Plain Text Passwords

This scenario is highly unlikely as passwords are usually hashed. SCAYLE does not recommend this method due to the significant effort involved in complying with data protection regulations. However, if passwords are available in plain text, they can be configured via SCAYLE’s Admin API. During migration, SCAYLE will hash the password and save it, allowing users to log in with their known passwords right after the migration.

Password migration can be conducted using either SCAYLE’s internal customer ID or the reference key set during customer migration. In both cases, you’ll need to provide the password and set the hashingType to internal'. This step ensures SCAYLE uses its internal hashing logic to verify passwords when users try to log in. Below is an example payload for reference.

Example payload for migrating a plain text password:

json

Copy

Case 2: Migrating Known Hashed Passwords

This method is viable only if the same hashing function as SCAYLE’s is used.

Migrate the hashed passwords directly via SCAYLE Admin API. Use either SCAYLE’s internal customer ID or the customer reference key, ensuring you add the hash and set hashingType as internal.

Case 3: External Password Validation

• When choosing to validate passwords externally, migrate the passwords flagged as external.
• Utilize either SCAYLE’s internal customer IDs or the customer reference keys set during the customer migration.
• It's crucial to set the hashingType to external. The hash value you enter will be ignored in this process.
• Following a successful external validation, SCAYLE will then hash the password with its internal hashing mechanism. The system will subsequently update the hashingType to internal, removing the need for further external validations.

Example payload for external password validation:

json

Copy

For SCAYLE to call an external service, the service’s endpoint and credentials must be configured. This setup, due to security considerations, is an internal process at SCAYLE. If you need to set up an external validation service, please contact your SCAYLE representative

Please be aware that you can configure different services for each shop country, each with its unique URL. As of now, SCAYLE supports only basic authentication for these services.

Handling Non-Migratable Passwords

Prerequisites: To utilize this option, ensure the password reset functionality is activated in SCAYLE.

In cases where password migration isn't possible, you still have the option to migrate customers with all their personal data and leverage SCAYLE’s password reset feature. This approach involves SCAYLE accepting the provided password, securely hashing it using its internal mechanism, and then categorizing the password as internal.

To initiate the password reset process, you can use SCAYLE’s Admin API. This process requires sending a distinct POST request for each customer in every shop country. Similar to the password migration process, you have the flexibility to use either SCAYLE’s internal customer IDs or the customer reference keys assigned during the migration.
POST /shops/{shopKey}/countries/{countryCode}/customers/{customerIdentifier}/send-reset-password-email

In case of errors, SCAYLE will provide detailed information within the error message. Here are some common responses you might encounter:

Importing additional customer data

In addition to basic information, you can also import extra customer data into SCAYLE, such as details about customer groups or memberships. For guidance on specific cases or further information, please refer to the SCAYLE Admin API documentation or contact your SCAYLE representative.

Deleting a customer

SCAYLE also offers endpoints for deleting imported customers and their addresses. This functionality is particularly useful during data migration testing, allowing you to perform retry loads with the same customer data. For further instructions on using these endpoints, please refer to the AdminAPI Delete Customer and Customer Address Endpoints.

Migrating orders to SCAYLE

To migrate orders, utilize SCAYLE’s Admin API. This section will guide you through the process of successfully migrating your orders to SCAYLE.

Importing an order

Before migrating orders, ensure that both customers and product data are already migrated to SCAYLE. It’s crucial to have customer and product reference keys available for accurate matching in the order payload.

Orders, including all related elements, can be imported to SCAYLE using the import order endpoint of SCAYLE's Admin API. Note that only closed orders can be imported directly into SCAYLE. Orders that are still active must first be completed in your legacy system.

Below is an example of an order that can be migrated. Please note that not all fields in that example are mandatory. For detailed information on required and optional data fields, review the documentation here.\

Example Payload to import an order

json

Copy

Deleting an order

SCAYLE offers an endpoint specifically for deleting imported orders. This feature is particularly useful during data migration testing, allowing for the re-import of the same orders if needed. For detailed guidance on using this endpoint, please refer to the Delete Order Endpoint documentation.

SCAYLE error handling and validations during the migration process

Evaluation of the data Import

SCAYLE’s endpoints are designed to support and streamline the data migration process with robust error handling capabilities:

Validation errors - HTTP 422

Here’s an example of a validation error you might encounter:

Error for an Import Request missing required referenceKey:\

json

Copy

Each error object in the response provides specific details about where the error occurred. We also offer a JSON validation schema for the request body to assist in error prevention.

Additional considerations for data migration

Here are some additional considerations for the data migration process:

• Size of Data: The larger the data set, the longer the migration process may take.
• Complexity of Data: Complex data requires more time for extraction, validation, and loading.
• Resource Availability: The availability of resources like hardware and software impacts the migration timeline. Discuss scaling API resources with your SCAYLE consultant to efficiently handle large data volumes.