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

# Referrals template Liquid reference

The `referrals.liquid` template controls the native Firmhouse referrals page opened by the dashboard referral banner. Edit it in the Customer Portal template editor to change the page layout, move or remove sections, and add your own content. Preview a saved version before publishing it.

This page uses customer referral data and the existing native referral eligibility rules. Its content lives in template translations, independently of the legacy portal copy settings. ReferralCandy is a separate integration. Native referrals must be enabled for customers to access this page.

Until you publish `referrals.liquid`, customers continue to see the legacy referral page, its configured copy, and the shared `other.liquid` wrapper. Draft previews are isolated from customers. Publishing a saved version or the Firmhouse default adopts the new page and enables the native banner in the default dashboard. Publishing Dashboard first does not enable that banner. Resetting Referrals restores the legacy page and hides the default banner again.

Customizations to `other.liquid` are not copied into `referrals.liquid`; apply any required layout changes before publishing. Existing custom dashboards are not rewritten, and explicitly authored referral tags remain under their template's control. Legacy presentation settings stay editable while the legacy page is active.

The default template contains the invitation, copy/share controls, referral history, and empty-state HTML directly. Edit their markup, styles, labels, and conditions in Liquid, just like the orders template. Shared navigation uses `{% navbar %}`.

## Available data

Page variables include `page_title`, `page_byline`, `subscription`, `project`, and `referrals`. Copy button labels use the `referrals.copy_label` and `referrals.copied_label` translations.

Use `{{ share_icons.email }}`, `{{ share_icons.whatsapp }}`, and `{{ share_icons.twitter }}` to render the existing sharing icons. These contain SVG markup rendered by Rails; insert them without escaping. The surrounding links remain editable in Liquid.

| Referral field | Description |
| - | - |
| `referrals.code` | The customer's native referral code, or nil. |
| `referrals.reward_discount` | Formatted reward discount for the default explanation. |
| `referrals.email_url` | Prepared email sharing URL. |
| `referrals.whatsapp_url` | Prepared WhatsApp sharing URL. |
| `referrals.twitter_url` | Prepared X sharing URL. |
| `referrals.rewards_count` | Number of activated referral rewards for this subscription. |
| `referrals.successful_referrals` | Successful referrals for this subscription, newest first. Each exposes `subscription_id`, `created_at`, and the localized `display_date`. |

Escape codes, URLs, dates, and other text when inserting them into HTML. Customize `referrals.message` through template translations. The `t` filter sanitizes this rich text; the default template preserves line breaks with `newline_to_br`. Without a custom message, the page shows the localized reward explanation.

```liquid theme={null}
{% if referrals.code != blank %}
  <p>{{ referrals.code | escape }}</p>
  <a href="{{ referrals.email_url | escape }}">Share by email</a>
{% endif %}

{% for referral in referrals.successful_referrals %}
  <p>{{ referral.display_date | escape }}</p>
{% endfor %}
```

The default template hides copy/share actions without a code and hides history without successful referrals. Keep the existing `clipboard` Stimulus controller and its data attributes when customizing the copy button.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.