curl -X POST 'https://api.snagsolutions.io/api/referral/codes' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"loyaltyRuleId": "558bcf56-24f1-4ef4-9787-043086295780"}'

{
  "id": "ref_123",
  "websiteId": "web_456",
  "organizationId": "org_789",
  "referralCode": "FRIEND2024",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": null,
  "userId": "user_abc"
}

​
Overview

This 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.
Token Hold

​
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 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.
curl -X POST 'https://api.snagsolutions.io/api/referral/codes' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"loyaltyRuleId": "558bcf56-24f1-4ef4-9787-043086295780"}'

{
  "id": "ref_123",
  "websiteId": "web_456",
  "organizationId": "org_789",
  "referralCode": "FRIEND2024",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": null,
  "userId": "user_abc"
}

​
Step 2: Create Referral User

When someone uses a referral code, use the Create referral user endpoint to register the referral relationship. 
curl -X POST 'https://api.snagsolutions.io/api/referral/users' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"userIds": ["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"]}'

{
  "message": "Referral user created successfully"
}

​
Step 3: Retrieve Referral Data

Use the Get referrals endpoint to retrieve all registered referrals in the system for monitoring and analytics purposes. 
curl -X GET 'https://api.snagsolutions.io/api/referrals' \
  -H 'X-API-KEY: YOUR_API_KEY'

​
Implementation Flow

1

User Registration

Create a new user in your Snag system using your existing user management endpoints.
2

Generate Referral Code

Call the create referral code endpoint to generate a unique referral code for the user.
3

Referral Tracking

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.
4

Monitor Referrals

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.