Help Center

ReferralCandy Liquid

Last Updated: Mar 28, 2017

Introduction

Liquid is an open-source template language created by Shopify. ReferralCandy uses Liquid to enable you to insert dynamic content in emails and pages in your referral marketing campaign. 

For example, you might want to include each advocate’s name in the referral email. In the example below, “Amy” is the name of an advocate and you want to insert each advocate’s names into emails: 

“Hi Amy! You are awesome!" 

You can do this by using the first_name attribute of the advocate object that is available in the referral email template: 

“Hi {{ advocate.first_name }}! You are awesome!" 

{{ advocate.first_name }} will be replaced by each advocate's name when the emails are sent out to each advocate. 


Page Content 

 

Basics of filters & tags

(go to top)

You can use all standard filters and standard tags listed in the Liquid for Designers documentation.

In addition, ReferralCandy provides a few additional filters and tags for your use:
 
Filter Description Example
candy_image_url Returns the URL of ReferralCandy-hosted images {{ 'icons/censored.png' | candy_image_url }}
t Returns the translated string stored in "locales" folder based on the specified translation key  {{ 'page.sharing.share_panel_expiry_note' | t }}
Tag
Description
Example
form
Returns the <form> html tag, see the specific page for details about the form tag usage within the page.
{% form 'registration_form' %}
 ...
{% endform %}
layout
Selects the layout to use for the page.
There are two layouts to choose from ‘page’ and ‘embed’ layouts.
Defaults to the ‘page’ layout if no layout is specified.
Adding this line to a page:

{% layout 'embed' %}

Will cause the page to use the ‘embed’ layout when it is rendered. 

Liquid Variables 

(go to top) 

Layout Variables 

(go to top)

These 3 liquid variables MUST be included in layout file i.e. layouts/page.liquid or layouts/embed.liquid:

Layout Variables
Description
Example
{{ content_for_header }}
Place it between the opening and closing <head> tag. It inserts the necessary scripts for analytics and referral tracking purpose.
<head>
 ...
 {{ content_for_header }}
</head>
{{ content_for_layout }}
Place it between the opening and closing <body> tag. It renders the page content.
<body>
 ...
 {{ content_for_layout }}
 ...
</body>
{{ content_for_footer }}
Place it right before the closing </body> tag. It inserts necessary scripts for analytics and tracking.
 ...
 {{ content_for_footer }}
</body>

Global Variables 

(go to top)

These liquid variables can be used in all templates:

Global Variable
Description
Example
{{ template }}
The current template code name (e.g. sharing_page, rewards_page)
<body class="{{ template }}">
{{ locale }}
ISO 639-1 language code e.g. 'en', 'zh-TW'
{% if locale == 'en' %}
 ...
{% endif %}
{{ is_embed }}
true if the page is rendered as embedded, otherwise false
{% if is_embed == false %}
 ...
{% endif %}
{{ hide_offer }}
true if the page should be Friend Offer coupon code (when an advocate attempts to click on their own referral link), otherwise false
{% if hide_offer %}
 ...
{% endif %}
{{ flash }}
contains errors or informational messages to be shown on a page
<div id='alerts'>{{ flash | default_flash }}</div>
{{ now }}
returns the current time when template is rendered
{% if purchase.review_deadline > now %}
{% endif %}

List of Liquid objects

(go to top)

This is a list of all the liquid objects that ReferralCandy supports. Each email or page has different liquid objects that each are able to access, which we will go through in the next section.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
advocate
The offer object contains information about the Friend Offer that is given to the advocate to give to his friends at the point when the referral link was generated.
advocate
The reward object contains information about the specific reward that the advocate has earned.
advocate
A list of rewards earned by the advocate.
 
You can use
 
{% for reward in rewards %}
  ...
{% endfor %}
 
to access each earned reward. See reward for a list of reward information that you can use.
campaign
The offer_setup object contains information about the Friend Offer as you have it currently configured for your referral campaign on your dashboard.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.
advocate
A list of purchases made by the advocate’s friends that count towards a reward, but are still within the review period.
 
You can use
 
{% for referred_purchase in pending_referred_purchases %}
 …
{% endfor %}
 
to access each pending referred purchase. See purchase for a list of purchase information that you can use.
advocate’s friends
Purchase made by the advocate’s referred friend at your store.

Liquid objects available to each page or email

(go to top)

Each email or page has different liquid objects that each are able to access. See the list below to determine what each page or email has access to:

Referral Email

(go to top)

Referral emails are sent to advocates to invite them to join your referral program. They encourage advocates to share your product with their friends. 

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
advocate
The offer object contains information about the Friend Offer that is given to the advocate to give to his friends at the point that the referral link is generated.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.

Reminder Email

(go to top)

Reminder Emails are sent to advocates at fixed intervals to keep them updated on the latest offerings of your referral program. They also encourage them to share your product with their friends.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
advocate
The offer object contains information about the Friend Offer that is given to the advocate to give to his friends at the point that the referral link is generated.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.

Advocate Join Page

(go to top)

The Advocate Join Page explains what your referral program is about and invites visitors to fill in their details to join your referral program.

Object
Scope
Description
campaign
The offer_setup object contains information about the Friend Offer as you have it currently configured for your referral campaign on your dashboard.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.
Forms
Description
registration_form
Form tag that allows you to embed a form into your page that visitors can use to register for your referral program.

Advocate Sharing Page

(go to top)

The Advocate Sharing Page is a page specific to an advocate that contains the referral link and social media sharing buttons the advocate can use to share about your referral program.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
advocate
The offer object contains information about the Friend Offer that is given to the advocate to give to his friends at the point that the referral link is generated.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.

Friend Offer Landing Page

(go to top)

The Friend Offer Landing Page is shown to an advocate's friend when they click on the advocate's referral link. It displays a Friend Offer coupon code that can be used at your store, and encourages the friend to start shopping.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
The offer object contains information about the Friend Offer that is given to the advocate to give to his friends at the point that the referral link is generated.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign campaign The campaign object contains general information about your shop.

Reward Pending Email

(go to top)

The Reward Pending Email is sent to an advocate the moment ReferralCandy detects that a purchase is made through the advocate's referral link.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
offer_setup campaign
The offer_setup object contains information about the Friend Offer as you have it currently configured for your referral campaign on your dashboard.
reward_setup campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.

Reward Successful Email

The Reward Successful Email is sent to an advocate when a referral they've made becomes eligible for a reward.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
referral_link advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
advocate specific reward
The reward object contains information about the specific reward that the advocate had earned.
campaign
The campaign object contains general information about your shop.

Reward Ineligible Email

(go to top)

The Reward Ineligible Email is sent to an advocate when a referral they've made (that was pending review) is cancelled, or when the associated purchase was returned.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
referral_link advocate A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
campaign
The campaign object contains general information about your shop.

Advocate Create Password Page

(go to top)

The Advocate Create Password Page tells advocates to create a password to access their Rewards Page.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
campaign
The campaign object contains general information about your shop.
Forms
Description
set_password_form
Form tag that allows you to include a form in the page for the advocate to specify the password for their account.

Advocate Login Page

(go to top)

The Advocate Login Page is a page unique to the advocate with a login form. Once they submit the correct email and password, they will be redirected to their Rewards Page.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
campaign
The campaign object contains general information about your shop.
Forms
Description
signin_form
Form tag that allows you to include a sign in form (with email and password fields).

Advocate Rewards Page

(go to top)

The Advocate Rewards Page is where advocates configure their rewards settings, and view their referral activity history, as well as earned rewards.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
advocate
A list of rewards earned by the advocate.
 
You can use {% for reward in rewards %} to access each earned reward. See reward for a list of reward information that you can use.
advocate
A list of purchases made by the advocate’s friends that count towards a reward, but are still within the review period.
 
You can use
 
{% for referred_purchase in pending_referred_purchases %}
 …
{% endfor %}
 
to access each pending referred purchase. See purchase for a list of purchase information that you can use.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.
Forms
Description
cash_rewards_option_form
Form tag that allows you to include a form that allows the advocate to choose how they want the cash reward to be delivered.

Advocate Messaging Preferences Page

(go to top)

The Advocate Messaging Preferences Page is where advocates configure their preference for the frequency in which they receive emails sent on your behalf by ReferralCandy.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
campaign
The campaign object contains general information about your shop.
Forms
Description
messaging_preferences_form
Form tag that allows you to include a form that allows the advocate to change messaging frequency.

Post-Purchase Popup

(go to top)

The Post-Purchase Popup shows up right after each advocate’s purchase, to encourage them to share your product with their friends.

Object
Scope
Description
advocate
The advocate object contains information about the advocate.
advocate
A unique link given to each advocate when they are enrolled in your referral program. The referral_link object contains information about this unique link (we call this the referral link) of the advocate.
advocate
The offer object contains information about the Friend Offer that is given to the advocate to give to his friends at the point that the referral link is generated.
campaign
The reward_setup object contains information about the Referral Reward as you have it currently configured for your referral campaign on your dashboard.
campaign
The campaign object contains general information about your shop.

Liquid Objects

(go to top)

These are all the liquid objects supported by ReferralCandy. Some liquid objects can only be used in certain templates.

advocate

(go to top)

Information about a person who has been enrolled in your referral campaign.

Object
Description
advocate.first_name
An advocate's first name.
advocate.last_name
An advocate's last name.
advocate.email
An advocate's email address.
advocate.portal
Information about an advocate's ReferralCandy Portal (see advocate.portal object).
advocate.cash_reward_settings
A liquid object that contains information about cash reward settings selected by an advocate. See below objects for more details.
advocate.cash_reward_settings.payout_option
If given a choice (depending on what you set for your campaign’s rewards), the advocate is able to select between various methods of receiving cash rewards.
 
This variable shows the cash payout option that is selected by an advocate.
 
Valid values - 'paypal', 'paypal_gift', 'donation'.
advocate.cash_reward_settings.paypal_email
An advocate's PayPal email address. This variable is available when payout option is set to 'paypal'
advocate.cash_reward_settigns.donation_charity_option
The charity selected by an advocate to donate the cash reward to.

advocate.portal

(go to top)

Information about an advocate's ReferralCandy Portal.

Object
Description
advocate.portal.code
An advocate's Portal Code. E.g. The advocate’s Referral Portal link is acme.referralcandy.com/XSVDY0C XSVDY0C is the Portal Code.
advocate.portal.sharing_page_url
The URL of the advocate's Sharing Page.
advocate.portal.rewards_page_autologin_url
The Portal Rewards Page Auto-Login URL. Clicking this link allows your advocate to automatically login to and access their Private Portal Rewards page.
advocate.portal.rewards_page_url
The URL of the advocate’s Private Portal Rewards Page
advocate.portal.logout_url The URL to logout advocate’s Private Portal Rewards Page
advocate.portal.messaging_preferences_page_url
The URL of the advocate’s Messaging Preferences Page.
advocate.portal.unsubscribe_url

(Alias for advocate.portal.messaging_preferences_page_url)
 
The URL of the advocate’s Messaging Preferences Page.
advocate.portal.contact_interval
The interval of receiving referral/reminder emails (in days) that an advocate has selected.
 
If the advocate did not change the message sending frequency before, this defaults to the ‘Sending Frequency’ that you set in the ‘Campaign Settings’ page.
 
For example,
5 means an advocate receives emails every 5 days.
0 means an advocate always receives emails based on campaign settings.
36525 means an advocate will never receive emails.
advocate.portal.contact_interval_mapping_for_select
The available email sending interval options that the advocate can select from. This is primarily used to build the select box in a form in the Messaging Preferences page.

campaign

(go to top)

Information about the referral campaign.

Object
Description
campaign.shop_url
The Store URL that was set in the Store Settings page in your ReferralCandy Dashboard.
campaign.shop_name
The Store Name that was set in the Store Settings page in your ReferralCandy Dashboard.

offer

(go to top)

Information about the Friend Offer that was given to the advocate to give out to friends at the point that the referral link is generated.

Object
Description
offer.description
Description of the Friend Offer that was given to the advocate at the point that the referral link is generated.

Returns the description specific by the retailer if offer.type is coupon or discount_link.
Returns nil if
offer.type is none.
offer.code
The coupon code of the Friend Offer that was given to the advocate at the point that the referral link is generated.

Returns the coupon code if offer.type is coupon.
Returns nil if
offer.type is none or discount_link.
offer.expiry_date
The expiry date of the Friend Offer that was given to the advocate at the point that the referral link is generated.
This will be nil if the Friend Offer has no expiry date.
offer.type
Type of Friend Offer that was given to the advocate at the point that the referral link is generated.

Valid types are coupon, discount_link and none.

offer_setup

(go to top)

Friend Offer settings of the referral campaign as you have it currently configured for your referral campaign on your dashboard.

Object
Description
offer_setup.description
The description of the Friend Offer as they are currently in the Offer page of the ReferralCandy dashboard.

pending_referred_purchases

(go to top)

Referred purchases of an advocate that count towards rewards, but are still within the review period.


You can use {% for purchase in pending_referred_purchases %} to access each pending referred purchase. See purchase for a list of purchase information that you can use.

purchase

(go to top)

Purchase made by a customer in your store.

Object
Description
purchase.review_deadline
A timestamp for the end of the review period for the purchase.
E.g. The below if statement returns true if the purchase review deadline is in the future (i.e. not yet passed).
 {% if purchase.review_deadline > now %}
purchase.date_purchased
The timestamp of when the purchase was made.

referral_link

(go to top)

A unique link given to each advocate when they are enrolled in your referral program. When a advocate's friend clicks on their referral link, the friend will be brought to a landing page, which shows them the coupon code (Friend Offer) that can be used at your store.

Object
Description
referral_link.url
The URL of the referral link.
referral_link.redirect_to_shop
The Store URL that was set in the Store Settings page in your ReferralCandy Dashboard.
referral_link.share_via_email
A link to a URL that accepts a POST request to send out a referral email to the advocate. The advocate can then share the referral email with friends.

Note: referral_link.share_via_email cannot be used in email templates.
E.g.
<form id="share-via-email-form" action="{{ referral_link.share_via_email }}" method="POST">
referral_link.share_via_facebook
A link to a URL that, when clicked, shows a Facebook dialog that allows the advocate to post directly to Facebook with pre-filled content.
The pre-filled content can be set at the Sharing Messages page of your ReferralCandy dashboard.
referral_link.share_via_twitter
A link to a URL that, when clicked, shows a Twitter dialog that allows the advocate to post directly to Twitter with pre-filled content.
The pre-filled content can be set at the Sharing Messages page of your ReferralCandy dashboard.

reward

(go to top)

A Referral Reward earned by an advocate.

Object
Description
reward.status
Referral Reward fulfilment status.
Valid values:
'unable_to_deliver' - Usually used when an advocate hasn't selected their preferred cash reward payout option.
'pending_fulfilment' - The reward is awaiting preparation by the retailer or system.
'shipped' - The reward has been sent out to an advocate.
'delivered' - The reward has been received by the advocate.
reward.description
The description of the reward.
reward.coupon_expiry_date
The expiry date that was set for the reward. It returns nil if there isn’t an expiry date set.
reward.coupon_code
The coupon code of the reward. It returns nil if the reward isn’t a coupon code reward.
reward.type
The type of the reward that was given out.
Valid values are: coupon, cash, custom
reward.date_earned
The timestamp for when the reward was earned.
reward.date_delivered
The timestamp when reward was received/claimed by advocate.

reward_setup

(go to top)

Referral Reward settings of the referral campaign as you have it currently configured for your referral campaign on your dashboard.

Object
Description
reward_setup.description
The description of the Referral Reward as it is currently set in the Rewards Page of your ReferralCandy dashboard.
reward_setup.type
The type of Referral Reward that is currently selected in the Rewards Page of your ReferralCandy dashboard.
Valid values - coupon, cash, custom
reward_setup.cash_reward_payout_options
The available cash payout options that are currently selected in the Rewards Page of your ReferralCandy dashboard if you selected cash rewards.
Valid values are: paypal, paypal_gift, donation
reward_setup.donation_charity_options
Available donation charity options.

rewards

(go to top)

Referral Rewards earned by an advocate.

You can use {% for reward in rewards %} to access each earned reward. See reward for a list of reward information that you can use.

Still have questions? Contact us.

Have other questions? Contact us.

support@referralcandy.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete