> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snagsolutions.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Refer a Friend
> Referral loyalty rule. Reward users for inviting friends to join your platform.
## **Overview**
This loyalty rule rewards users for referring others, with multiple reward structures supporting first-level and second-level referrals. An admin sets up a referral program where User X gets 1000 points for each new referral, and new users (User Y) get 500 points upon joining. Additionally, User X earns 10% of User Y's earnings and 5% of User Z's earnings. This rule is checked daily, ensuring that referrers continue to earn from their referrals' activity over time.
## **Rule Configuration Fields**
* **Referral Reward Amount for Referrer**: When User X refers to User Y, User X gets rewarded..
* **Points Rewarded to New User**: When User X refers to User Y, User Y gets an initial reward.
* **Percentage Points to Reward for First Referral**: When User X refers to User Y, User X can earn a percentage of Y's earnings based on cadence (daily/weekly/monthly).
* **Percentage Points to Reward for Second Referral**: When User X refers to User Y, and Y refers to User Z, both X and Y can earn a percentage of Z's earnings.
### **Update Cadence**
The Update Cadence field is crucial as it defines:
* **Reward Frequency**: This is only applicable to percentage based rewards, this determines how often the user will receive rewards (e.g., Daily, Weekly, Monthly).
* **Relation to Start Time**: The first verification of all the referrals and reward distribution will begin at the defined Start Time. Subsequent verifications and rewards will follow the selected cadence (e.g., if the cadence is set to "Daily," the system will check and reward holdings every 24 hours from the Start Time).
### **Custom Settings**
Users qualify for referral rewards based on conditions such as achieving points, completing profile details, or connecting social accounts.
## **API Usage**
For API partners, referral rules can be implemented programmatically using the Snag API. After creating a user in Snag, you'll need to follow these steps to set up referrals:
### **Step 1: Generate Referral Code**
Use the [Create referral code](/api-reference/referrals/create-referral-code) endpoint to generate a unique referral code for a user. This code will be used to track referrals.
This endpoint can be treated as both "create" and "get" - it will not generate
a new code if the user already has one. Instead, it will return the existing
referral code, making it safe to call multiple times.
See the [API reference](/api-reference/referrals/create-referral-code) for response structure.
### **Step 2: Create Referral User**
When someone uses a referral code, use the [Create referral user](/api-reference/referrals/create-referral-user) endpoint to register the referral relationship.
See the [API reference](/api-reference/referrals/create-referral-user) for response structure.
### **Step 3: Retrieve Referral Data**
Use the [Get referrals](/api-reference/referrals/get-referrals) endpoint to retrieve referral details including eligibility status and points earned at each tier level. The response includes:
* **`eligible`**: Whether the referred user meets eligibility requirements
* **`amount`**: Direct referral fixed amount
* **`tier1Amount`**: Points earned from tier-1 referrals
* **`tier2Amount`**: Points earned from tier-2 referrals
See the [API reference](/api-reference/referrals/get-referrals) for complete response structure.
The `amount`, `tier1Amount`, and `tier2Amount` fields only return data for earnings after 2025-04-24.
### **Step 4: Retrieve Referral Points**
Snag doesn't store referral points as a single aggregated number per user. Query [Loyalty Transaction Entries](/api-reference/loyalty/get-loyalty-transaction-entries) using `userId` and `loyaltyRuleId` to get all referral point transactions. See the [API reference](/api-reference/loyalty/get-loyalty-transaction-entries#parameter-loyalty-rule-id) for details.
To display a total referral points balance, aggregate these entries on your side. See [Managing Rule-Level Points](/loyalty/manage-rule-level-points) for the recommended approach.
Combine both endpoints: use Get Referrals to show referred friends and their status, and use Loyalty Transaction Entries to show transaction history and calculate totals.
### **Viewing Referrals in Looker Studio**
If your organization has **Looker Studio** access enabled through Snag, you can view referral data directly in your CRM Looker view without using the API.
To view referred users:
1. Navigate to your CRM Looker Studio dashboard
2. Open the **"referred users"** tab
3. Filter by a specific wallet address to see all users referred by that address
Filtering by wallet address allows you to quickly identify all users that were
referred by a specific referrer, making it easy to track referral performance
and relationships.
If Looker Studio is **not yet set up** for your organization, [contact us](https://www.snagsolutions.io/contact) to request access or an extension of your existing Looker Studio dashboard. The Snag team can help you enable the integration and ensure your referral data is automatically synced for full visibility.
### **Implementation Flow**
Create a new user in your Snag system using your existing user management endpoints.
Call the create referral code endpoint to generate a unique referral code for the user.
When a new user signs up using a referral code, call the create referral user endpoint to establish the referral relationship.
Ensure you're calling this endpoint with the correct user IDs to properly link referrer and referee.
Use the get referrals endpoint to retrieve referral data for analytics, reporting, or user dashboard displays.
The referral rule will automatically process rewards based on your
configuration once the referral relationship is established through the API
calls.
### **Quest Chaining with Referral Rules**
When using quest chaining to link a referral rule to another quest, the referral reward system works as follows:
* **Referrer Eligibility**: The user who made the referral (referrer) will only become eligible for rewards after the referred user completes the chained quest
* **Quest Completion Requirement**: The referred user must successfully complete the linked quest before any referral rewards are processed
* **Automatic Processing**: Once the chained quest is completed, the referral rule automatically processes and distributes rewards according to your configuration at the specified cadence (daily/weekly/monthly)
If quest chaining is enabled, referral rewards will not be processed until the
chained quest is completed by the referred user, regardless of when the
referral relationship was established.