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

# referrals

> Access a list of the customer's referrals, including their status and details.

## Syntax

<Tabs>
  <Tab title="Liquid">
    ```liquid theme={null}
    customer.metafields.lantern.referrals
    ```
  </Tab>
</Tabs>

## Description

The `referrals` contains a JSON string representing an array of referral objects associated with the customer. This metafield is automatically updated whenever a referral's status changes or a new referral is created for the customer.

Each object in the array represents a single referral and includes details such as its `id`, `status`, `createdAt`, `updatedAt`, and the `friendEmail` of the referred customer.

<Warning>
  The `referrals` metafield stores the data as a JSON string. Parse the string before accessing individual referral objects in Liquid.
</Warning>

## Properties

**Type:** `String` (JSON string)
**Namespace:** `lantern`

## Return Values

| Scenario                   | Value                                                             | Type   |
| -------------------------- | ----------------------------------------------------------------- | ------ |
| Customer has referrals     | JSON string of referral array (e.g., `"[{\"id\":\"123\", ...}]"`) | String |
| Customer has no referrals  | `"[]"`                                                            | String |
| Not eligible for referrals | `null`                                                            | null   |
| Logged out                 | `null`                                                            | null   |

## Examples

### Displaying Customer's Referrals

```liquid theme={null}
{% assign referrals_json = customer.metafields.lantern.referrals %}

{% if referrals_json != blank %}
  {% assign referrals = referrals_json | parse_json %}
  {% if referrals.size > 0 %}
    <div class="customer-referrals">
      <h4>Your Referrals</h4>
      <ul>
        {% for referral in referrals %}
          <li>
            Referral ID: {{ referral.id }}<br>
            Friend Email: {{ referral.friendEmail }}<br>
            Status: {{ referral.status }}<br>
            Created At: {{ referral.createdAt | date: "%B %d, %Y" }}
          </li>
        {% endfor %}
      </ul>
    </div>
  {% else %}
    <p>You currently have no referrals.</p>
  {% endif %}
{% else %}
  <p>You currently have no referrals.</p>
{% endif %}
```