Referral Program Metaobject
The Referral Program metaobject allows you to configure and manage referral rewards for both referring and referred customers. This documentation covers how to access and use the metaobject in your Shopify store.
Accessing the Metaobject
To access the Referral Program metaobject in your Liquid templates, use the following code:
_10{%- assign referral_program = shop.metaobjects.app--60169453569--referral_program.v2 -%}
Available Fields
The Referral Program metaobject contains the following fields:
| Field Name | Type | Description |
|---|---|---|
is_active | Boolean | Controls whether the referral program is currently active |
referring_customer_gets_type | Text | Type of reward for referring customer ('PERCENTAGE' or 'FIXED') |
referring_customer_gets_value_percentage | Decimal | Percentage reward for referring customer |
referring_customer_gets_value_money | Money | Fixed amount reward for referring customer |
referring_customer_expiry_days | Integer | Days until referring customer's reward expires |
referring_customer_availability_delay_days | Integer | Days before referring customer's reward becomes available |
referred_customer_gets_type | Text | Type of reward for referred customer ('PERCENTAGE', 'FIXED' or 'FREE_SHIPPING') |
referred_customer_gets_value_percentage | Decimal | Percentage reward for referred customer |
referred_customer_gets_value_money | Money | Fixed amount reward for referred customer |
referred_customer_minimum_order_value | Money | Minimum order value required for referred customer |
referred_customer_must_be_new_customer | Boolean | Whether the referred customer must be new |
cookie_duration_in_days | Integer | Duration of the referral tracking cookie |
Example Usage
Here's a complete example of how to display the Referral Program settings in your Liquid template:
_68{%- comment -%} Referral Program {%- endcomment -%}_68{%- assign referral_program = shop.metaobjects.app--60169453569--referral_program.v2 -%}_68{% if referral_program %}_68<h2>Referral Program</h2>_68<table class="program-table">_68 <tr>_68 <th colspan="2">Program Status</th>_68 </tr>_68 <tr>_68 <td>Is Active</td>_68 <td>{{ referral_program.is_active }}</td>_68 </tr>_68_68 <tr>_68 <th colspan="2">Referring Customer Rewards</th>_68 </tr>_68 <tr>_68 <td>Reward Type</td>_68 <td>{{ referral_program.referring_customer_gets_type }}</td>_68 </tr>_68 {% if referral_program.referring_customer_gets_type == 'PERCENTAGE' %}_68 <td>Reward Amount</td>_68 <td>{{ referral_program.referring_customer_gets_value_percentage }}%</td>_68 {% elsif referral_program.referring_customer_gets_type == 'FIXED' %}_68 <td>Reward Amount</td>_68 <td>{{ referral_program.referring_customer_gets_value_money.value | money }}</td>_68 {% endif %}_68 <tr>_68 <td>Expiry Days</td>_68 <td>{{ referral_program.referring_customer_expiry_days }}</td>_68 </tr>_68 <tr>_68 <td>Availability Delay</td>_68 <td>{{ referral_program.referring_customer_availability_delay_days }}</td>_68 </tr>_68_68 <tr>_68 <th colspan="2">Referred Customer Rewards</th>_68 </tr>_68 <tr>_68 <td>Reward Type</td>_68 <td>{{ referral_program.referred_customer_gets_type }}</td>_68 </tr>_68 {% if referral_program.referred_customer_gets_type == 'PERCENTAGE' %}_68 <td>Reward Amount</td>_68 <td>{{ referral_program.referred_customer_gets_value_percentage }}%</td>_68 {% elsif referral_program.referred_customer_gets_type == 'FIXED' %}_68 <td>Reward Amount</td>_68 <td>{{ referral_program.referred_customer_gets_value_money.value | money }}</td>_68 {% endif %}_68 <tr>_68 <td>Minimum Order Value</td>_68 <td>{{ referral_program.referred_customer_minimum_order_value.value | money }}</td>_68 </tr>_68 <tr>_68 <td>Must Be New Customer</td>_68 <td>{{ referral_program.referred_customer_must_be_new_customer }}</td>_68 </tr>_68_68 <tr>_68 <th colspan="2">Program Settings</th>_68 </tr>_68 <tr>_68 <td>Cookie Duration</td>_68 <td>{{ referral_program.cookie_duration_in_days }} days</td>_68 </tr>_68</table>_68{% endif %}
Field Details
| Field Name | Type | Purpose | Usage |
|---|---|---|---|
is_active | Boolean | Controls the overall activation state of the referral program | Use this to conditionally enable or disable the entire referral functionality |
referring_customer_gets_type | Text | Defines how the referring customer's reward is calculated | Can be either 'percentage' or 'fixed', determines which value field to use |
referring_customer_gets_value_percentage | Decimal | Percentage-based reward for referring customer | Only used when referring_customer_gets_type is 'percentage' |
referring_customer_gets_value_money | Money | Fixed amount reward for referring customer | Only used when referring_customer_gets_type is 'fixed' |
referring_customer_expiry_days | Integer | Number of days until the referring customer's reward expires | Use to communicate reward expiration to customers |
referring_customer_availability_delay_days | Integer | Days before referring customer's reward becomes available | Helps manage the delay between referral and reward availability |
referred_customer_gets_type | Text | Defines how the referred customer's reward is calculated | Can be either 'percentage' or 'fixed', determines which value field to use |
referred_customer_gets_value_percentage | Decimal | Percentage-based reward for referred customer | Only used when referred_customer_gets_type is 'percentage' |
referred_customer_gets_value_money | Money | Fixed amount reward for referred customer | Only used when referred_customer_gets_type is 'fixed' |
referred_customer_minimum_order_value | Money | Minimum purchase amount required for referred customer to qualify | Use to enforce minimum spend requirements for referral rewards |
referred_customer_must_be_new_customer | Boolean | Controls whether only new customers can receive referral rewards | Use to restrict referral rewards to new customer acquisition |
cookie_duration_in_days | Integer | Number of days the referral tracking cookie remains valid | Determines how long a referral link remains associated with a customer |
Best Practices
- Always check if the metaobject exists before accessing its properties:
_10{% if referral_program %}_10 // Your code here_10{% endif %}
- Handle both reward types appropriately:
_10{% if referral_program.referring_customer_gets_type == 'PERCENTAGE' %}_10 {{ referral_program.referring_customer_gets_value_percentage }}%_10{% else %}_10 {{ referral_program.referring_customer_gets_value_money.value | money }}_10{% endif %}
- Format monetary values using the money filter:
_10{{ referral_program.referred_customer_minimum_order_value.value | money }}
- Consider the delay and expiry periods when displaying reward information:
_10{% assign available_date = 'now' | date: '%s' | plus: referral_program.referring_customer_availability_delay_days | times: 86400 | date: '%Y-%m-%d' %}_10Reward will be available on: {{ available_date }}