memberr Docs

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:

{%- assign referral_program = shop.metaobjects.app--60169453569--referral_program.v2 -%}
{% if referral_program %}
<p>{{ referral_program.is_active }}</p>
{% endif %}

You can use the following liquid code to display a customers referral link:

{{shop.domain}}/?memberr-ref={{customer.id}}

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:

{%- comment -%} Referral Program {%- endcomment -%}
{%- assign referral_program = shop.metaobjects.app--60169453569--referral_program.v2 -%}
{% if referral_program %}
<h2>Referral Program</h2>
<table class="program-table">
  <tr>
    <th colspan="2">Program Status</th>
  </tr>
  <tr>
    <td>Is Active</td>
    <td>{{ referral_program.is_active }}</td>
  </tr>

  <tr>
    <th colspan="2">Referring Customer Rewards</th>
  </tr>
  <tr>
    <td>Reward Type</td>
    <td>{{ referral_program.referring_customer_gets_type }}</td>
  </tr>
  {% if referral_program.referring_customer_gets_type == 'PERCENTAGE' %}
    <td>Reward Amount</td>
    <td>{{ referral_program.referring_customer_gets_value_percentage }}%</td>
  {% elsif referral_program.referring_customer_gets_type == 'FIXED' %}
    <td>Reward Amount</td>
    <td>{{ referral_program.referring_customer_gets_value_money.value | money }}</td>
  {% endif %}
  <tr>
    <td>Expiry Days</td>
    <td>{{ referral_program.referring_customer_expiry_days }}</td>
  </tr>
  <tr>
    <td>Availability Delay</td>
    <td>{{ referral_program.referring_customer_availability_delay_days }}</td>
  </tr>

  <tr>
    <th colspan="2">Referred Customer Rewards</th>
  </tr>
  <tr>
    <td>Reward Type</td>
    <td>{{ referral_program.referred_customer_gets_type }}</td>
  </tr>
  {% if referral_program.referred_customer_gets_type == 'PERCENTAGE' %}
    <td>Reward Amount</td>
    <td>{{ referral_program.referred_customer_gets_value_percentage }}%</td>
  {% elsif referral_program.referred_customer_gets_type == 'FIXED' %}
    <td>Reward Amount</td>
    <td>{{ referral_program.referred_customer_gets_value_money.value | money }}</td>
  {% endif %}
  <tr>
    <td>Minimum Order Value</td>
    <td>{{ referral_program.referred_customer_minimum_order_value.value | money }}</td>
  </tr>
  <tr>
    <td>Must Be New Customer</td>
    <td>{{ referral_program.referred_customer_must_be_new_customer }}</td>
  </tr>

  <tr>
    <th colspan="2">Program Settings</th>
  </tr>
  <tr>
    <td>Cookie Duration</td>
    <td>{{ referral_program.cookie_duration_in_days }} days</td>
  </tr>
</table>
{% 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:

{% if referral_program %}
  // Your code here
{% endif %}

Handle both reward types appropriately:

{% if referral_program.referring_customer_gets_type == 'PERCENTAGE' %}
  {{ referral_program.referring_customer_gets_value_percentage }}%
{% else %}
  {{ referral_program.referring_customer_gets_value_money.value | money }}
{% endif %}

Remember to use .value for money fields and to format monetary values using the money filter:

{{ referral_program.referred_customer_minimum_order_value.value | money }}

Consider the delay and expiry periods when displaying reward information:

{% assign available_date = 'now' | date: '%s' | plus: referral_program.referring_customer_availability_delay_days | times: 86400 | date: '%Y-%m-%d' %}
Reward will be available on: {{ available_date }}

Listing a Customer's Referrals

You can fetch the list of referrals a customer has generated using the global memberrJS object, which the Memberr Shopify app exposes on the storefront.

The API

memberrJS.getCustomerReferralList(customerId)

It returns a promise that resolves with the following shape:

{
  "organization": {
    "currency": "EUR"
  },
  "referrals": [
    {
      "created_at": "2025-01-15T10:30:00Z",
      "referred_customer": {
        "name": "Jane Doe"
      },
      "store_credit": {
        "amount": 1000,
        "currency": "EUR"
      }
    }
  ]
}

store_credit.amount is returned in the smallest currency unit (e.g. cents). Divide by 100 before formatting.

Minimal example

The snippet below renders the customer's referrals as a plain HTML list. Drop it into any Liquid template (section, page, snippet) - no styling or section settings required.

{% if customer %}
  <div id="referrals">
    <p id="referrals-loading">Loading referrals...</p>
    <p id="referrals-error" hidden>Could not load referrals.</p>
    <p id="referrals-empty" hidden>You haven't referred anyone yet.</p>
    <ul id="referrals-list" hidden></ul>
  </div>

  <script>
    document.addEventListener('DOMContentLoaded', function () {
      var loadingEl = document.getElementById('referrals-loading');
      var errorEl   = document.getElementById('referrals-error');
      var emptyEl   = document.getElementById('referrals-empty');
      var listEl    = document.getElementById('referrals-list');

      // 1. Make sure the Memberr storefront SDK is available.
      if (typeof memberrJS === 'undefined') {
        loadingEl.hidden = true;
        errorEl.hidden = false;
        return;
      }

      // 2. Fetch the referral list for the currently logged-in customer.
      memberrJS
        .getCustomerReferralList('{{ customer.id }}')
        .then(function (data) {
          loadingEl.hidden = true;

          // 3. Handle the empty state.
          if (!data.referrals || data.referrals.length === 0) {
            emptyEl.hidden = false;
            return;
          }

          // 4. Render each referral as a list item.
          data.referrals.forEach(function (referral) {
            var date   = new Date(referral.created_at).toLocaleDateString();
            var name   = referral.referred_customer.name;
            var amount = (referral.store_credit.amount / 100).toFixed(2);
            var currency = referral.store_credit.currency;

            var item = document.createElement('li');
            item.textContent = date + ' - ' + name + ' - +' + amount + ' ' + currency;
            listEl.appendChild(item);
          });

          listEl.hidden = false;
        })
        .catch(function (error) {
          console.error('Failed to fetch referrals:', error);
          loadingEl.hidden = true;
          errorEl.hidden = false;
        });
    });
  </script>
{% else %}
  <p>Please <a href="/account/login">log in</a> to see your referrals.</p>
{% endif %}

What's happening

The customer ID is rendered server-side via {{ customer.id }} and passed to memberrJS.getCustomerReferralList(...).
The promise resolves with an organization object and an array of referrals.
Each referral is rendered as an <li> with date, referred customer name and the awarded store credit.
Loading, error and empty states are toggled via the hidden attribute so the markup stays declarative.

The customer must be logged in for customer.id to be available. The example wraps everything in {% if customer %} to handle the logged-out case.

Referrals

On this page