Stage History Migration in Zoho CRM

Data Migration - PickList / Stage History

Quick Overview:

In Zoho CRM, PickList history allows you to track changes made to PickList fields that represent the status of a record. For example, in the Deals module, the Stage PickList field helps track how a deal moves through different sales stages like Qualification → Proposal → Negotiation → Closed Won/Lost.

Info
Note :
PickList migration can be done for any PickList field where history tracking for PickList is turned on.

Import Method:

PickList history in a Module can only be imported using Data Migration. Module level import is not supported for PickList history.

Data Migration:


The Data Migration feature in Zoho CRM facilitates the automatic mapping of import files to their corresponding CRM modules, as well as the mapping of columns within the files to specific Zoho CRM fields. During this process, the Migration ID plays a vital role. A Migration ID is a unique identifier provided for each record during data migration. When importing data using the Data Migration tool, it is mandatory to provide the Migration ID for every record. This identifier serves as a reference point, ensuring the accurate linking and association of records into Zoho CRM.

NotesPermission:
Only users with Data Migration permissions in their profile can access this feature.

This document explains the detailed steps to migrate Stage History. The same procedure can be applied to migrate history for other PickList fields as well.

Prerequisites:

  1. All import files must be in CSV format.
  2. To perform stage history migration, it is mandatory to first import the parent records (Deals) via the Data Migration. This step is essential to obtain the Migration ID of the parent records, which is required to map the stage history data to the appropriate deal records correctly.
  3. Two separate CSV files must be prepared for import:
    1. Deal Module File
    2. Stage History Data File

Steps to perform migration:

We will be taking Deal Record and Deal Stage History as an example for this Article.

Step 1: Prepare the Deal record file


Prepare the CSV file for importing Deal records. Ensure the file contains the following columns which is necessary for the Migration:
  1. Deal Id (Migration id)
  2. Deal Name
  3. Stage



Notes
Note:
Created Time and Modified Time fields can be included. If not specified, the record's Created Time will default to the date and time it was imported.
Please ensure that all mandatory fields are provided during the import process.

Step 2: Prepare the Stage history file


Create a separate CSV file for stage history data. The below mentioned fields are mandatory to import stage history.
  1. Deal Id
  2. Stage History Id
  3. Stage
  4. Probability
  5. Modified time
Notes
Note:
The Modified Time of the stage history must be after the Created Time of the Deal record and before the Modified Time of the Deal record.
  1. Modified by
Notes
Note :
Update user id in the Modified By column: Export the Users file from
Setup > Data Administration > Export > Get the Id of the specific user from the file and use it in the Modified by column.

Info
Sample Format :
To be used for the Modified By column "zcrm_6649548000000559001"



Step 3: Navigate to Data Migration Import


Zoho CRM > Setup > Data Administration > Import > Choose Zoho CRM.

Step 4: Upload the CSV files


Select and upload both CSV files:
  1. Deal record File
  2. Stage history File



Step 5: Assign Modules to Files


Once the data is processed, Select the Deals module and assign the corresponding file. Select the Stage history section and assign the stage history data file.

Step 6: Map Fields


Map all mandatory fields in both the Deals and Stage history files to the appropriate fields in Zoho CRM.

Deals Module Field Mapping :



Stage History Field Mapping:



Step 7: Proceed with Migration


After completing the field mapping, continue with the migration process.

Info
Video Example:
You can access the detailed screen recording where I demonstrate the complete migration process and results, along with sample CSV files for both the Deals module (parent record) and the stage history, from this link.

Common Errors when importing stage history in Zoho CRM


Modified Time of the history cannot be before the Created Time of the Parent record



If the Modified Time in the stage history is earlier than the Created Time of the deal record, this error will occur.

To resolve this, navigate to the deal record and check its Created Time. Ensure that the Modified Time in the stage history is set after the record's Created Time.

Example:
If the record's Created Time is 24-04-2025 07:02, then the Modified Time in the stage history must be after 24-04-2025 07:02 to avoid the error.

Date value cannot be in future - Modified time.




Modified Time of the history cannot be after the Modified Time of the Parent record - Modified time.

Ensure that the Modified Time of the stage history is earlier than the Modified Time of the parent Deal record.

Example:
If the Deal record's Modified Time is 29-04-2025 07:02, then the Modified Time of the stage history should be before 29-04-2025 07:02.

Duplicate records exist in system - Stage History Id.



If a previously used Migration ID is reused while importing stage history entries, the above mentioned error will occur. To prevent this, ensure that each stage in the import file has a unique Migration ID.


Quote
Custom Solution Created by Madhu Sree | Zoho Partner Support.

If you need any further clarifications, please don’t hesitate to contact partner-support@zohocorp.com.

NotesAdditionally, we kindly ask all "Europe and UK partners" to reach out to partner-support@eu.zohocorp.com.