View desktop instructions

View mobile app instructions
Import Your Referral Program Data

Published on: Mon, 9 Sep, 2024 at 9:28 AM | Updated on: Wed, 18 Jun, 2025 at 7:49 AM

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
Enable a clean break from legacy systems
Reintroduce your referral program with excitement and clarity

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.
User data
Referral data
Reward data
This includes emails, referral codes, sharelinks , and custom fields. Affiliates should be filtered out to avoid double rewards.
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. Download an example of the required fields or make use of the example below in .csv format.
```
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. Download an example of the required fields or make use of the example below in .csv format.
```
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.
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 <unitName>/<Currency> (E.g., Cash/USD).
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.
Download an example of the required fields or make use of the example below in .csv format.
```
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
```

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.

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 wallet, give users a grace period to redeem. Use email or in-app reminders to nudge early referral activity in the new program.

Validation error reference

You can get 3 types of validation errors:

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 .
- MISSING_FIELD — e.g., a required field such as User ID or Account ID is missing.
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.
Listed errors: these appear as a list of error counts on the Imports & Exports screen when the import type doesn't have a preview validation table. Row errors and file errors will display together: