Sync your Customer.io people with ReferralCandy to enroll them in your referral program as advocates — and optionally write each advocate's unique referral link back to Customer.io, so you can drop referral links straight into your Customer.io campaigns and newsletters.

With the Customer.io integration you can:

Import your contacts from Customer.io into ReferralCandy — everyone, or a single Customer.io segment — and enroll them as advocates in your referral campaigns.
Write each advocate's referral link back to Customer.io as a custom attribute — one per campaign — you can use in your emails and data-driven segments (optional).
Send real-time ReferralCandy events (such as RC - Enrolled and RC - Reward earned) to Customer.io, so your own automations can react when someone joins your referral program or earns a reward (optional).
Enroll new subscribers in real time with a Customer.io reporting webhook, so people join your referral program the moment they subscribe (optional).

Note: Connecting Customer.io does not change how ReferralCandy's own emails behave — and ReferralCandy never sends emails through Customer.io. But contacts you import are enrolled as advocates, so they will start receiving whichever ReferralCandy emails you have turned on (such as the welcome email). Decide before your first sync whether you want both tools emailing your contacts — see Who sends the emails below.

Before you start

To set up the Customer.io integration, you'll need access to your ReferralCandy dashboard and a Customer.io workspace where you can view API credentials.

Have your Customer.io App API key ready. In Customer.io, go to Settings → API Credentials → App API keys — or click Get API key next to the field in ReferralCandy to open the right page. Customer.io shows an App API key's secret only once, when the key is created — if you didn't save yours, just create a new App API key.
Check whether your Customer.io workspace is hosted in the United States or the European Union — you'll select this Region during setup.
If you also want referral links written back to Customer.io and real-time ReferralCandy events (see Steps 3 and 4), grab your Site ID and Track API key too — they're shown together on Customer.io's API Credentials page.

Step 1: Connect Customer.io

Go to your Integrations → Customer.io page:
- From the ReferralCandy dashboard (my.referralcandy.com), go to Integrations and select the Customer.io tab.
- From your Shopify admin, go to Integrations → Customer.io.
Under Status you'll see the connection badge — it starts as Not connected.
Paste your Customer.io App API key into the App API key field. If you don't have one yet, click Get API key next to the field to open Customer.io's API Credentials page.
Choose your Region — United States or European Union — to match where your Customer.io workspace is hosted.
(Optional) Under Write referral links back (optional), enter your Site ID and Track API key if you want ReferralCandy to write each advocate's referral link back to Customer.io and send real-time referral events (see Step 3 and Step 4). Leave both blank to import contacts only.
Click Connect. You'll see a "Connected to Customer.io" confirmation, and the badge changes to Connected.

Having trouble connecting? Double-check that you pasted your App API key (not your Track API key) and that the Region matches your Customer.io workspace, then try again.

Step 2: Import your contacts

Once connected, a Sync contacts section appears below the Status card.
Use the Import from segment dropdown to choose which Customer.io contacts to import — All people, or one of the segments from your Customer.io workspace. (These are your Customer.io segments, not your ReferralCandy segments.)
Click Sync now. You'll see a "Customer.io sync started" confirmation.
The import runs in the background — larger lists can take a while, so check back a little later.

Imported people are added as contacts in ReferralCandy and enrolled into your campaigns as advocates. ReferralCandy imports each person's email address, first and last name, and their other Customer.io attributes — the email address arrives first, and names and other attributes can fill in a few minutes later, so don't worry if a fresh import briefly shows email addresses only. People without an email address are skipped. On Shopify stores, imported contacts also appear as customers in your Shopify admin.

The sync runs when you click Sync now — it isn't a recurring schedule. You can sync with Customer.io as often as you like: existing contacts are updated, never duplicated. To add new subscribers automatically without re-syncing, set up the real-time webhook in Step 5.

Remember: newly enrolled advocates receive whichever ReferralCandy emails you have turned on — including the welcome email. If you don't want that, turn those emails off before you sync (see the next section).

Who sends the emails — ReferralCandy, Customer.io, or both?

Connecting Customer.io does not turn off ReferralCandy's own emails, and ReferralCandy never sends emails through your Customer.io workspace. Both tools run independently, so it's up to you how to split the work:

Use both (most common): ReferralCandy keeps sending its referral program emails (welcome, reminder, reward, and payout notifications), while you use Customer.io for your newsletters and campaigns — dropping each advocate's referral link in with the rc_referral_link_<campaign short code> attribute (see Step 3).
Send only from Customer.io: if you'd rather all emails come from Customer.io, turn ReferralCandy's campaign emails off manually. Go to Campaigns, open your campaign, and select Emails — each email type (welcome, reminder, the reward emails, cash payout) has its own toggle, and the one-time win-back email only sends if you schedule it. Repeat for each active campaign. The events in Step 4 carry the data you'd need — reward amounts, coupon codes, the portal sign-in link — to rebuild ReferralCandy's reward notifications as your own Customer.io emails.

Turning ReferralCandy emails off? Do it before running your first sync — otherwise newly enrolled advocates will receive the ReferralCandy welcome email. It's also manual in both directions: if you later disconnect Customer.io, ReferralCandy's emails don't switch back on by themselves — re-enable them yourself.

Step 3: Write referral links back to Customer.io (optional)

If you entered your Site ID and Track API key when connecting, ReferralCandy writes custom attributes to each imported person in Customer.io:

rc_referral_link_<campaign short code> — the person's unique referral link for that campaign. The attribute name ends with the campaign's short code in lowercase — for example, a campaign with short code FREN writes rc_referral_link_fren. If you run more than one campaign, each referral or affiliate campaign writes its own referral-link attribute — loyalty campaigns don't have referral links, so they don't add one.
referralcandy_advocate — set to true, so you can build a data-driven segment in Customer.io of everyone in your referral program.

Your campaign short code is shown under Campaigns → your campaign → Campaign details — it's set when the campaign is created, it's locked once the campaign has been activated, and it's not the same as your campaign name. See [Shopify] Creating a campaign or [Other Platforms] Creating a campaign for more on the short code.

You can then drop the referral link into any Customer.io email using Liquid:

{{ customer.rc_referral_link_fren }} (with your own campaign's short code in place of "fren")

For example, add it to your newsletter footer — "Share the love and earn rewards: {{ customer.rc_referral_link_fren }}" — or use it as the destination of a button. The referral link is how referred friends claim your friend offer and shop at your store — see friend offer landing page for what friends see when they open it.

You don't have to type the attribute name from memory: in the Customer.io email editor, open the Personalization panel, choose Profile Attributes as the data type, and click the rc_referral_link_... attribute to insert it — Customer.io adds the Liquid for you, with a preview of the actual link.

Connected without Track API credentials? The Customer.io integration works in import-only mode. To turn write-back on later, disconnect (see Disconnecting Customer.io) and reconnect with the App API key, Region, Site ID, and Track API key all filled in — then click Sync now again so referral links are written for your existing advocates. Referral events (see Step 4) also start flowing once your Track credentials are saved.

Step 4: ReferralCandy events in Customer.io (optional)

With your Site ID and Track API key in place, ReferralCandy also sends real-time events to Customer.io whenever there's referral activity. Events appear on the person's profile activity in Customer.io with names starting with RC - , and you can use them to trigger your own Customer.io campaigns and automated journeys based on referral progress.

ReferralCandy sends an event when someone joins your referral program, earns a reward, or makes a successful referral. Events you'll see include:

RC - Enrolled — the person joined one of your campaigns (loyalty campaigns included). Includes the campaign name and whether it's their first-time enrollment.
RC - Subscribed to campaign emails — the person was subscribed to your campaign's emails.
RC - Purchase referred by profile detected — ReferralCandy detected a referred purchase from this person. Includes the campaign name, purchase amount, and currency. It fires at detection, which can be before the purchase is approved.
RC - Reward earned — the person earned a referral reward. Includes the campaign name, date earned, and the reward type, amount, and currency — plus the coupon code and expiry date for coupon rewards, or the advocate's portal sign-in link for cash rewards.

Each event carries the campaign name as an event variable, so your automations can tell campaigns apart. You can see every event type your workspace has received under Data index → Events in Customer.io.

You can also use these events to send your own emails from Customer.io — for example, your own version of the reward notification. Create an event-triggered automation (in Customer.io, go to Automations and use the RC event as the trigger), and the email editor's Personalization panel then offers that event's variables under the Events data type — so you can drop in the reward amount, the coupon code, or the portal sign-in link. If you rebuild a ReferralCandy email this way, turn the matching ReferralCandy email off (see Who sends the emails above) so advocates don't receive both.

Attributes vs. event data: ReferralCandy stores only the two attributes from Step 3 on each person's profile (rc_referral_link_... and referralcandy_advocate) — those are available in any email under Profile Attributes. Event data — the reward amount, coupon code, purchase amount, and so on — travels with each event instead of being stored on the profile, so it's only available in emails triggered by that event, under the Events data type.

Building an automation on RC - Enrolled? Your first sync enrolls everyone you import, so the RC - Enrolled event fires for each imported contact. If you don't want an enrollment automation to run for your whole imported list, set it live after your initial import.

Step 5: Enroll new subscribers in real time (optional)

Instead of re-running the sync to pick up new subscribers, you can have Customer.io notify ReferralCandy the moment someone subscribes:

In ReferralCandy, go to Integrations → Customer.io and find Real-time new subscribers (optional) in the Status section.
Copy Your webhook URL using the Copy button.
In Customer.io, go to Integrations, open the Directory tab, and select Reporting webhooks (searching "webhook" in the directory finds it fastest) to open the Add Reporting Webhook form. Set the Webhook endpoint to the URL you just copied, and under Customer Events, tick the Subscribed event — that's the "customer subscribed" signal ReferralCandy listens for.
Click Save and Enable Webhook — the plain Save button creates the webhook but leaves it switched off. Customer.io then shows a signing key for the webhook. Paste it into the Webhook signing secret field in ReferralCandy and click Save. You'll see "Webhook signing secret saved".

From then on, when someone's subscription status in Customer.io changes to subscribed, they're enrolled in your referral program within seconds. This works when your signup method records whether the person is subscribed — if new profiles arrive with just an email address and nothing about their subscription, Customer.io doesn't send the event, and those people are picked up on your next sync instead.

Important: The signing secret lets ReferralCandy verify that events really come from your Customer.io workspace — the webhook won't work until the signing secret is saved, so don't skip that step. Make sure you paste the signing key shown for the reporting webhook you created, not the workspace-level key on Customer.io's "Webhook signing keys" tab under API credentials — they're different keys. Only the Subscribed event is used; other events sent to the webhook are ignored.

Disconnecting Customer.io

Go to your Integrations → Customer.io page and click Disconnect Customer.io in the Status section.
Confirm by clicking Disconnect in the dialog. You'll see "Disconnected from Customer.io".

After disconnecting the Customer.io integration:

ReferralCandy stops importing contacts from Customer.io, stops updating people in Customer.io, and stops sending referral events.
Attributes already written (the rc_referral_link_... attributes and referralcandy_advocate) stay on your people in Customer.io until you remove them there.
Advocates who were already enrolled stay in your referral program — disconnecting doesn't remove them from ReferralCandy.
If you turned ReferralCandy's campaign emails off while using Customer.io, remember to turn them back on (Campaigns → your campaign → Emails) — disconnecting doesn't re-enable them for you.

Customer.io integration FAQ & troubleshooting

Common questions about the Customer.io integration:

Will my contacts get emails when I sync?

Nothing is sent through Customer.io when you sync — ReferralCandy never emails your contacts from your Customer.io workspace. However, imported contacts are enrolled as advocates in your ReferralCandy campaigns, so they will receive whichever ReferralCandy emails are turned on — typically the welcome email. If you don't want that, turn those emails off before syncing (see "Who sends the emails" above).

Can I use both ReferralCandy emails and Customer.io at the same time?

Yes — many merchants use both ReferralCandy emails and Customer.io together. ReferralCandy handles the referral program emails while Customer.io handles newsletters and campaigns (with each advocate's referral link available as an rc_referral_link_... attribute — see Step 3 above). If you'd rather send everything from Customer.io, turn ReferralCandy's campaign emails off manually under Campaigns → your campaign → Emails — connecting the integration doesn't turn them off for you.

Which API key does the Customer.io integration need?

Connecting the Customer.io integration requires your App API key. The Site ID and Track API key are only needed if you want referral links written back to Customer.io and real-time ReferralCandy events — leave them blank and the integration simply imports contacts.

Customer.io shows an App API key's secret only once, when the key is created. If you no longer have yours, create a new App API key in Customer.io (Settings → API Credentials → App API keys) and use that — unused old keys can be deleted there too.

I clicked Connect and got an error

An error when connecting Customer.io is almost always a credentials issue. Check that you pasted the App API key (a Track API key won't work here), that the Region matches where your Customer.io workspace is hosted, and that no extra spaces were copied along with the key. If it still fails after that, our support team can take a look at your account — just let us know.

I clicked Sync now but don't see my contacts yet

The Customer.io import runs in the background and processes your list in batches, so a large list can take a while. Check your contacts a little later. Contacts can also appear with just their email address at first — names and other attributes fill in a few minutes behind. Keep in mind that only people with an email address are imported. If contacts are still missing after a few hours, our support team can check the sync on your account — just let us know.

Will new subscribers be added automatically?

The Customer.io sync runs only when you click Sync now. To enroll new subscribers automatically, set up the real-time reporting webhook (see "Enroll new subscribers in real time" above) — otherwise, re-run the sync whenever you want to pick up new people.

Can I sync more than once? Will that create duplicates?

You can sync with Customer.io as often as you like — existing contacts are updated, never duplicated.

What exactly does ReferralCandy write to my Customer.io people?

ReferralCandy writes two kinds of data to your Customer.io people. First, custom attributes: an rc_referral_link_<campaign short code> referral-link attribute for each referral or affiliate campaign, and referralcandy_advocate set to true. Second, real-time events named RC - ... (like RC - Enrolled or RC - Reward earned) triggered by referral activity. It never changes your other Customer.io attributes, and never sends emails through Customer.io.

Where do I find my campaign short code?

Your campaign short code — the code at the end of the rc_referral_link_... attribute name — is shown under Campaigns → your campaign → Campaign details. It's set when the campaign is created and can only be edited while the campaign is still in setup; once the campaign has been activated, the short code is locked. It's also not the same as your campaign name — renaming a campaign doesn't change its short code. See [Shopify] Creating a campaign or [Other Platforms] Creating a campaign for details.

Why do I only see two ReferralCandy variables in the email editor?

In a regular Customer.io broadcast or newsletter, the Personalization panel shows profile attributes — and ReferralCandy stores exactly two on each person: rc_referral_link_... (the referral link, one per campaign) and referralcandy_advocate. The event variables — reward amount, coupon code, portal sign-in link, purchase amount — aren't profile attributes: they travel with each RC - ... event, so they only appear when you're editing an email inside an automation triggered by that event (choose Events as the data type in the Personalization panel). See Steps 3 and 4 above for the two kinds of data.

My real-time webhook isn't enrolling new subscribers

If the real-time webhook isn't enrolling new Customer.io subscribers, work through these checks:

The webhook URL in Customer.io exactly matches the one shown in ReferralCandy.
The Subscribed event (under Customer Events) is enabled on the reporting webhook.
The webhook signing secret is pasted and saved in ReferralCandy — events are ignored until the secret is saved.
The signing secret you pasted is the one shown for the reporting webhook itself — not the workspace-level key from Customer.io's "Webhook signing keys" tab.
The new subscriber has an email address — people without one aren't enrolled.

Testing it yourself? Adding a profile in Customer.io by hand won't trigger the webhook — Customer.io only sends the event when a profile's subscription status is actually written, and adding someone by hand doesn't write it. To test the loop, take an existing profile, unsubscribe it, then resubscribe it.

If it still isn't working after these checks, our support team can dig in — just let us know.

Integration: Using ReferralCandy with Customer.io