Welcome, Guest Login

Support Center

ReferralCandy Liquid

Last Updated: Aug 02, 2016 06:54AM UTC

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 page content)

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 page content) 

Layout Variables (go to page content)

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 page content)

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 page content)

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

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.


 

offer

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.

reward

advocate

The reward object contains information about the specific reward that the advocate has earned.

rewards

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.

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

campaign

The campaign object contains general information about your shop.

pending_referred_purchases

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.

purchase

advocate’s friends

Purchase made by the advocate’s referred friend at your store.


 
 

Liquid objects available to each page or email (go to page content)

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 page content)

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

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.



 

offer

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.

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

campaign

The campaign object contains general information about your shop.

 

Reminder Email (go to page content)

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

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.


 

offer

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.

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

campaign

The campaign object contains general information about your shop.

 

Portal Access Page (go to page content)

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

 

Object

Scope

Description

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

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.

 

Portal Sharing Page (go to page content)

The Portal 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 Landing Page (go to page content)

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.
 

Pending Reward Email  (go to page content)

The Pending Reward 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

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.

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

campaign

The campaign object contains general information about your shop.

 

Successful Reward Email

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

Object

Scope

Description

advocate

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.

reward

advocate specific reward

The reward object contains information about the specific reward that the advocate had earned.

campaign

campaign

The campaign object contains general information about your shop.

 

Ineligible Reward Email (go to page content)

The Ineligible Reward 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

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

campaign

The campaign object contains general information about your shop.

 

Private Portal Create Password Page (go to page content)

The Private Portal Create Password Page instructs advocates to create a password to gain access to their Private Portal Rewards Page.
 

Object

Scope

Description

advocate

advocate

The advocate object contains information about the advocate.

campaign

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.

 

Private Portal Log-in Page (go to page content)

The Private Portal Log-in 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 Private Portal Rewards Page.

 

Object

Scope

Description

advocate

advocate

The advocate object contains information about the advocate.

campaign

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).

 

Private Portal Rewards Page (go to page content)

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

Object

Scope

Description

advocate

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.

rewards

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.

pending_referred_purchases

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.

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

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.



 

Portal Messaging Preferences Page (go to page content)

The Portal 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

advocate

The advocate object contains information about the advocate.

campaign

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 Widget (go to page content)

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

Object

Scope

Description

advocate

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.

offer

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.

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

campaign

The campaign object contains general information about your shop.

 

Liquid Objects (go to page content)

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

advocate (go to page content)

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 page content)

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 page content)

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 page content)

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 page content)

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 page content)

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 page content)

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 page content)

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 page content)

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 page content)

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 page content)

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.
 



 

 

support@referralcandy.com
http://assets2.desk.com/
false
referralcandy
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