> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up ReferralCandy referrals

> Use the native ReferralCandy integration in Firmhouse to run influencer and referral campaigns with your existing subscription customer base.

With the native ReferralCandy integration in Firmhouse, you can run influencer and referral campaigns with your subscription customer base.

This guide explains how to set up a campaign in ReferralCandy that rewards your existing subscriber with a discount on their next order or multiple orders, whenever they refer a friend to your store.

## Discount-code Based vs ReferralCandy Native

The Firmhouse integration with ReferralCandy is native. That means that a reward is automatically applied on an Advocate's subscription in Firmhouse.

If you don't use our native integration with ReferralCandy, or if you are using a different referral/loyalty app on Shopify, then usually advocates get a discount code emailed to them. And then they need to apply that discount code to get a reward.

The native Firmhouse integration makes the experience much smoother: whenever an advocate refers a friend successfully, the reward is automatically added to their existing subscription.

## Configuring ReferralCandy in Firmhouse

You'll need to copy-paste a few things from ReferralCandy into Firmhouse to follow the next steps. So it's convenient if you keep two tabs or browser windows open to configure.

### Steps

1. In your Firmhouse project, go to **New Features** in the sidebar of your project.
2. Enable the **ReferralCandy Integration** feature by clicking the toggle.
3. Now go to **Apps** in the Firmhouse sidebar, find **ReferralCandy** and click **Configure**.
4. In a different tab or browser screen, go to **ReferralCandy** in your Shopify store, and navigate to the **Account** menu item. It may be that this is initially hidden under a "View more" link that you need to click.
5. On the **Profile** tab (this should automatically already be open), scroll down to the **API Tokens** section. There copy-paste the **API Access ID** and **API Secret ID** into the same fields in Firmhouse.
6. If your ReferralCandy account has multiple campaigns, copy the Campaign ID for the active campaign you want to use and paste it into the optional **Campaign ID** field in Firmhouse. This makes sure Firmhouse creates invite links and fetches rewards for the correct campaign.
7. After saving your API tokens and optional Campaign ID, in the ReferralCandy configuration settings in Firmhouse, create and/or choose the Discount you would like to automatically apply to the Advocate's subscription.

## Customer Portal referral banner

When the ReferralCandy app is enabled and configured, the default Customer Portal dashboard shows a referral banner for subscribers who have a ReferralCandy invite link.

The banner encourages customers to share their personal referral link and includes:

* A short referral message
* A **More info** button that opens the customer's ReferralCandy invite page
* A **Share my personal link** button that copies the customer's ReferralCandy invite link

If the advocate reward discount configured in Firmhouse is active and valid for the subscription, the banner message includes the discount amount. For example, it can show a percentage discount or a fixed amount discount. If Firmhouse cannot confidently determine the discount for that subscription, the banner uses a generic referral message instead.

This banner is part of the default Customer Portal v2 dashboard template. If you use a customized `dashboard.liquid` template, make sure your template includes the ReferralCandy banner markup or an equivalent custom block that uses `subscription.referral_candy.url`.

The banner is only shown when Firmhouse can fetch a personal invite link from ReferralCandy for the subscription. If the ReferralCandy campaign is stopped, paused, or has settings that prevent invite links from being created, ReferralCandy may not return a link and the banner will stay hidden. A referral code stored in Shopify is not enough for this banner; the Customer Portal uses the invite link returned by ReferralCandy through the Firmhouse integration.

## Setting Up a Referral Campaign in ReferralCandy

Let's now set up a campaign in ReferralCandy:

### Steps

1. In ReferralCandy, go to **Campaigns** from the menu and click **Create new Campaign**.
2. Choose **Refer-a-Friend**.
3. Under **Set Rewards** click **Advocate reward** and then **Edit reward**.
4. Then as **Give advocates a free gift** reward type choose **Custom**. This allows Firmhouse to process any advocate rewards generated by this campaign, and apply them to subscriptions.
5. Save the Advocate reward and go back to setting up the rest of your campaign.
6. Set up your remaining campaign settings as you see fit, such as the name, identifiers, expiry, target audience, and advocates, etc.
7. Activate your campaign and use the normal ReferralCandy features to promote your campaign to your existing customer base.

## How Are Rewards Awarded to Advocates?

Once you've gone through all the above steps, your referral campaign should be good to go! There are a few important things to know to make sure everything works as expected:

* Whenever a friend uses a discount code at checkout, ReferralCandy takes 6 hours (or more, depending on your settings) to unlock the reward for the advocate.
* Firmhouse checks every hour if there are new advocate rewards unlocked in ReferralCandy, and then applies the reward to the advocate's subscription. If there are multiple subscriptions, the reward is applied to the subscription that has the closest billing date from today.
* If a subscriber already has an advocate reward pending for their next order, any new advocate rewards will be automatically queued to be applied for their subsequent orders. This is done by increasing the usage limit of the discount applied on the subscription in Firmhouse.

## Where Can I See Which Rewards Are Active on a Subscription?

When a configured discount gets rewarded to an advocate subscription, you can find them on the Customer detail page in the Firmhouse portal under the section **Applied Promotions**.

## Troubleshooting

### Why is the referral banner not visible in the Customer Portal?

The Customer Portal referral banner is hidden when Firmhouse cannot fetch a personal invite link from ReferralCandy.

Check the following:

* The ReferralCandy app is enabled in Firmhouse.
* The API Access ID and API Secret ID are saved in the ReferralCandy app settings in Firmhouse.
* The ReferralCandy campaign is active and allows invite links to be created.
* If your ReferralCandy account has multiple campaigns, the **Campaign ID** in Firmhouse matches the active campaign you want to use.
* If you use a customized Customer Portal `dashboard.liquid` template, the template includes a ReferralCandy block that uses `subscription.referral_candy.url`.

If ReferralCandy returns an error such as "Campaign is stopped", activate or update the campaign in ReferralCandy and then reload the Customer Portal. If you have more than one campaign, also check that Firmhouse is configured with the Campaign ID of the active campaign.

### Why is a referral discount not applied to a referrer?

If a referral discount is not being applied to a referrer (advocate), the referral may have been flagged as suspicious by ReferralCandy's automated fraud prevention system. ReferralCandy has built-in mechanisms to detect and prevent fraudulent referrals, such as self-referrals or referrals from the same household.

To investigate this, you can check the **Fraud Center** in your ReferralCandy dashboard. The Fraud Center allows you to view and manage referrals that have been flagged as potentially fraudulent, and you can choose to approve or reject them based on your own assessment.

For more information on how ReferralCandy handles fraud detection and how you can manage suspicious referrals, see the following ReferralCandy documentation:

* [How to handle fraud](https://help.referralcandy.com/en/articles/6643979-how-to-handle-fraud) - Learn how to manage and monitor suspicious referrals in the Fraud Center
* [Automated fraud prevention mechanisms](https://help.referralcandy.com/en/articles/2457877-automated-fraud-prevention-mechanisms) - Understand ReferralCandy's built-in fraud prevention measures
* [Viewing Fraud History (Shopify)](https://help.referralcandy.com/en/articles/6644001-shopify-viewing-fraud-history) - Check fraud-related past actions you've taken against an advocate