# Import Your Referral Program Data When switching from another referral platform to Advocate, you’re not just importing data — you’re upgrading your program’s potential with powerful tracking, customizable experiences, and expert support. This article walks you through: * Why migration matters * What a strategic migration plan looks like * What data can be imported * How to prepare your files * Common validation errors and how to avoid them #### Why plan a strategic migration? Migrating your referral program isn’t just a technical task — it’s a chance to level up how you engage and reward your customers. A well-planned migration helps: * Minimize disruption to your referral experience * Preserve historical data and ensure reward continuity ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media) * Enable a clean break from legacy systems * Reintroduce your referral program with excitement and clarity ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media) Referral and reward migration depend on your ability to export data from your current system. Your Advocate team can let you know what is possible based on the export data you provide. Your Advocate team will work with you to review your export files, identify what’s feasible, and create a plan that matches your program’s needs and goals. #### What you'll need to do * Export your program's *user data*, *referral data*, and *reward data*. Either contact your CSM on your old referral platform for assistance, or use an in-platform export tool if one is provided. * Download each of the 3 data reports in a separate CSV file, e.g., `user_data.CSV`, `referral_data.CSV`, and `reward_data.CSV`. * See the examples below for what each .csv file's contents could look like, or see the full Destination field reference. This includes emails, referral codes, sharelinks ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media), and custom fields. Affiliates should be filtered out to avoid double rewards. ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c11b6248bd7b0ef1b687330c8c79fba510517058%2Ff18ad34bbbcaa64fb7feb774bf5d7e154b2a259f3a75f2c3b60ec0ed3ed2371d.svg?alt=media) Dependent on sharelink format and usage of custom subdomain. The User Data file will contain detailed information about each participant in your program. Export a list of all participants to keep your program up-to-date with their share links and referral codes. The following fields are **required**: * User ID * Account ID Use the user’s email as their *user ID* and *account ID*. Dates should be formatted in [milliseconds since unix epoch](https://currentmillis.com/). Download an [example of the required fields](https://res.cloudinary.com/product-enablement/raw/upload/v1750169976/CSVs/Migration_User_Import_examples_-_User_Data.csv) or make use of the example below in `.csv` format. ```programlisting id,accountId,email,firstName,lastName,dateCreated,locale,countryCode,segments User1@example.com,User1@example.com,User1@example.com,First,Last,1741051242000,en_US,US, User2@example.com,User2@example.com,User2@example.com,First,Last,,,,"vip,newuser" User3@example.com,User3@example.com,User3@example.com,First,Last,,en_CA,, User4@example.com,User4@example.com,User4@example.com,First,Last,,,,newuser ``` This includes start and conversion dates, and referrer/referred relationships. It supports mapping historical referral performance. The referral data file provides a record of the status of each referral connection made in your referral program. The following fields are **required**: * Advocate User ID * Advocate Account ID * Referred User ID * Referred Account ID Use the user’s email as their *user ID* and *account ID*. Dates should be formatted in [milliseconds since unix epoch](https://currentmillis.com/). Download an [example of the required fields](https://res.cloudinary.com/product-enablement/raw/upload/v1750249453/CSVs/Migration_User_Import_examples_-_Referral_Data_-_Referral_Data.csv) or make use of the example below in `.csv` format. ```programlisting referrerUser,referrerAccount,referredUser,referredAccount,dateReferralStarted,dateConverted,programId User2@example.com,User2@example.com,User12@example.com,User12@example.com,1740824979000,1740824979000,33435 User1@example.com,User1@example.com,User13@example.com,User13@example.com,1741051242000,1741051242000,33435 User1@example.com,User1@example.com,User17@example.com,User17@example.com,,,33435 User1@example.com,User1@example.com,User18@example.com,User18@example.com,,,33435 ``` This includes values, dates given/redeemed, reward types, and statuses. It allows for preserving credibility and fairness with users. The Reward Data file provides a record of participant reward history, including their value and redeemed amount generated through your referral program. The following fields are **required**: * Advocate User ID * Advocate Account ID * Reward Name * Reward Unit * Reward Value * Date Created * Date Given * Date Redeemed * Redeemed Amount Use the user’s email as their *user ID* and *account ID*. Dates should be formatted in [milliseconds since unix epoch](https://currentmillis.com/). The Reward value is the numeric value of the reward in its smallest measurement unit (e.g., for a cash reward of $1.00, the value would be 100 cents). If the Reward unit is cash it should include the currency code in the following format `/` (E.g., Cash/USD). {% hint style="warning" %} **Important**: If the *Date Redeemed* and *Redeemed Amount* fields are not set appropriately — meaning they are either left blank or contain incorrect values (e.g., a future date or an inaccurate redeemed amount) — the reward may become available for the user to redeem again. {% endhint %} Download an [example of the required fields](https://res.cloudinary.com/product-enablement/raw/upload/v1750249453/CSVs/Migration_User_Import_examples_-_Reward_Data_-_Reward_Data.csv) or make use of the example below in `.csv` format. ```programlisting User ID,Acccount ID,Referred User ID,Referred Account ID,Reward Name,Reward Unit,Reward Value,Redeemed Amount,Date Created,Date Given,Date Redeemed User1@example.com,User1@example.com,User2@example.com,User2@example.com,Dollars,CASH/USD,1000,1000,1709712158000,1709712158000,1709712158000 User1@example.com,User1@example.com,User3@example.com,User3@example.com,Points,POINT,100,100,1726164909682,1726164909682,1726164909682 User1@example.com,User1@example.com,User4@example.com,User4@example.com,Points,POINT,100,100,1726164887075,1726164887075,1726164887075 User1@example.com,User1@example.com,User5@example.com,User5@example.com,Points,POINT,100,100,1726164875888,1726164875888,1726164875888 User1@example.com,User1@example.com,User6@example.com,User6@example.com,Points,POINT,10,10,1726164828986,1726164828986,1726164828986 User1@example.com,User1@example.com,User7@example.com,User7@example.com,Account Credit,USD,8000,8000,1726164289997,1726164289997,1726164289997 User1@example.com,User1@example.com,,,Gift Card,USD,10000,10000,1726163864871,1726163864871,1726163864871 User1@example.com,User1@example.com,,,Points,POINT,800,800,1726095906392,1726095906392,1726095906392 User1@example.com,User1@example.com,,,Gift Card,USD,30000,30000,1726163769157,1726163769157,1726163769157 User1@example.com,User1@example.com,,,20 Off,%,20,20,1726180309034,1726180309034,1726180309034 ``` {% hint style="warning" %} **Important:** All 3 export files should contain data from a single program only. If the files have data from multiple programs, the import will consolidate it into a single program. {% endhint %}
A sample migration plan Every migration is unique, but successful ones follow a similar structure that balances preparation, communication, and execution. Below is a migration plan that ensures continuity and a seamless experience for both your team and your advocates. Timelines and phases can flex depending on your program setup. **Phase 1: Planning and prep (1–2 weeks)** This is your foundation-setting stage, laying the groundwork for a smooth transition. | | | | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Goals |

• Align stakeholders.

• Technical setup.

• Confirm migration scope.

• Plan user communication.

| | Tasks |

• Secure a sample set of your historical data (users, referrals, rewards) and share with the Advocate team for review and field mapping .

• Export full data sets once the sample has been validated. The export data will most likely need to be manipulated (e.g., adjusting headers, field names, or file structure) to match the import requirements.

• Set a go-live date and rollback window.

• Add Advocate widgets in hidden mode (test environment or unlinked pages).

• Set up necessary integrations (e.g., Shopify, HubSpot, Segment).

• Complete program configuration in Advocate (e.g., rewards setup, program rules, email templates, segmentation).

• Test program functionality end-to-end — confirm that shares, conversions, and rewards track correctly in a test environment before going live.

• Draft messaging to communicate the transition to advocates.

Referral and reward migration depends on your ability to export data from your current system. Your Advocate team can let you know what is possible based on the export data you provide.

| | Tips |

• If you’re overlapping platforms, make sure only one is issuing rewards.

• Identify power users who may need special handling (VIPs, influencers).

| **Phase 2: Cutover and go live (1-2 days)** This is your transition moment. Plan for a brief pause in tracking between systems, and schedule during low-traffic hours if possible. | | | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Goals |

• Seamlessly switch from your legacy platform to Advocate.

• Ensure users can access the new experience immediately.

• Avoid loss of referral data or rewards.

| | Tasks |

• Remove old platform scripts/widgets from your site.

• Push Advocate widgets live.

• Import final user, referral, and reward data.

• Manually track/flag any conversions between system shutdown and launch.

• Monitor Advocate dashboard for activity.

• Send out launch communication to your advocates. Let users know that their referral links have been updated, and ideally include the new links directly in the email to make it easy for them to start sharing right away.

| | Tips |

• Include a short reward blackout buffer if necessary (e.g., “Referrals made on May 15 will be reviewed and added post-launch.”).

• Use advocate-facing communication to create excitement (e.g., “We’ve upgraded your referral experience!”).

| **Phase 3: Post-migration & cleanup (1–2 days)** Now that you’re live, ensure that your program is working as expected and address any loose ends. | | | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Goals |

• Verify data integrity and reward tracking.

• Capture any missed conversions.

• Support and educate users.

| | Tasks |

• Validate that referrer/referred relationships work in live mode.

• Import any missed conversions that occurred between cutover.

• Conduct a QA test (refer yourself, confirm tracking and reward logic).

• Provide internal and external FAQs or help docs.

• Monitor support inbox for issues related to legacy users.

| | Tips |

• If you’re sunsetting a legacy rewards funding account, give users a grace period to redeem.

• Use email or in-app reminders to nudge early referral activity in the new program.

|
#### Import your program's data 1. From the left navigation menu, select ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[Engage] → Reporting → Imports & Exports**. 2. In the top-right corner, select ![](https://4048883401-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-ec3276f07285180fbb2167a40e148d3e43e8681c%2F05aa88f72076df5a744d4620574f19cc187b7154fe1f3bb73ad7a892b7d23002.svg?alt=media) **Import**. 3. Select the *Import Type* from the available options: | Import Type | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Users | Select this option to upload new users or existing user data. You can also choose to import this data from a different account or platform. | | Update User Reward Balances | Select this option to update and redeem user reward balances. | | User Events | Select this option to upload user event data. | | Delete Users |

Select this option if you want to bulk delete existing users from your program.

You can also delete user handling and opt to:

• Preserve empty accounts

• Prevent deleted users from being created again

| | Reward History | Select this option to upload a record of all reward information. You can also choose to import this data from a different account or platform. | | Referral History | Select this option to upload a record of all referral connections. You can also choose to import this data from a different account or platform. | 4. Select **Choose File** or drag and drop the file you'd like to import. 5. Select **Import** to upload your data. * If bulk deleting existing users, select **Bulk Delete**. #### Validation error reference You can get 3 types of validation errors: 1. **Inline error message:** these appear in the preview validation table and cause error rows to be highlighted in red: * `INVALID_FIELD` — e.g., the *Date Created* field wasn't formatted in [milliseconds since unix epoch](https://currentmillis.com/) . * `MISSING_FIELD` — e.g., a required field such as *User ID* or *Account ID* is missing.
2. **Error callout:** these appear in place of the preview validation table as red warning messages: * `MISSING_HEADER` — e.g., a required column header such as *Account ID* or *Reward Value* is missing. * `CSV_PARSING` — e.g., the CSV file contains special characters that are improperly formatted. * `FILE_REF_IO` — e.g., the file is corrupted and can't be read.
3. **Listed errors:** these appear as a list of error counts on the *Imports & Exports* screen within the *Reporting* section when the import type doesn't have a preview validation table. Row errors and file errors will display together:
#### Support You don’t have to navigate migration alone. Our Advocate onboarding team is ready to help with: * Field mapping support * Data formatting guidance * Reward migration strategy * Testing and QA Contact your [Advocate support team](mailto:support-advocate@impact.com).