# Referrals
\nA very customisable referral system, with support for milestones, rewards, waiting to execute rewards until player joins back, custom messages, reminders on join, account join time limits, referral limits, circular referral blocking, and placeholders.<\/p>\n
## Config “`yaml # Prefix # Circlular referrals # Maximum referrals # Maximum age # Referree joined requirement # Notify on join # Notify delay # Messages # \/refer command messages # \/refer explanation (when no args provided) # Join notification messages # \/referral help command # \/referral command messages # \/referral config messages # Rewards # Milestone rewards # Individual milestone configurations # bStats # PlaceholderAPI Integration “`<\/p>\n<\/details>\n ## Placeholders All placeholders are also explained at the bottom of the config.yml file<\/p>\n ## Milestones <\/p>\n ## Permissions ## Commands # Support Let players get rewards for referring each other, fully customisable<\/p>\n","protected":false},"featured_media":131129,"template":"","meta":{"_minecraft_slug":"referrals","_minecraft_project_id":"8GMszC0L","_minecraft_author":"editid","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":17,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"referrals.zip","_minecraft_size_bytes":47063,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:44:31.588438Z","_minecraft_date_created":"2026-01-25T21:57:01.034824Z","_minecraft_date_modified":"2026-01-24T19:13:47.794398Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/referrals","_minecraft_icon_attachment_id":131129,"_minecraft_imported_at":"2026-06-07T17:30:49+00:00","_minecraft_import_hash":"474e6cb4f0c65d5706f22b4b0e93aa47","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,127,128,867,129,92],"mod_loader":[132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-131128","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-social","mod_category-spigot","mod_category-utility","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\nAll config options are explained in the config.yml file<\/p>\nconfig.yml<\/summary>\n
\n# _____ __ _ _ _
\n#| __ \/ _| | | | | (_)
\n#| |__) | ___ | |_ ___ _ __ _ __ __ _ | | _ __ | | _ _ __ _ _ _ __
\n#| _ \/ \/ _ | _| \/ _ | ‘__| | ‘__| \/ _` | | | | ‘_ | | | | | | \/ _` | | | | ‘_
\n#| | | __\/ | | | __\/ | | | | | (_| | | | | |_) | | | | |_| | | (_| | | | | | | |
\n#|_| _ ___| |_| ___| |_| |_| __,_| |_| | .__\/ |_| __,_| __, | |_| |_| |_|
\n# | | __\/ |
\n# |_| |___\/<\/p>\n
\n# The prefix to use in messages
\n# default: “&6&l[Referral]”
\nprefix: “&6&l[Referral]”<\/p>\n
\n# If player1 refers player2, can player 2 also refer player1?
\n# default: false
\ncircular-referrals: false<\/p>\n
\n# How many players can one player refer?
\n# Set to -1 for unlimited referrals
\n# default: -1
\nmax-referrals: -1<\/p>\n
\n# How many seconds can a user have played before they cannot run \/refer to claim their referral?
\n# Set to -1 for no limit
\n# default: 86400 (24 hours)
\nmax-age: 86400<\/p>\n
\n# Does the player that referred the player have to have joined the server before the referree joins?
\n# This helps prevent players from putting invalid usernames.
\n# default: true
\nreferree-joined-requirement: true<\/p>\n
\n# Should players that haven’t been referred be notified about the referral system on join, if the max-age hasn’t been exceeded?
\n# default: true
\nnotify-on-join: true<\/p>\n
\n# How long to wait (in milliseconds) before sending the notify message on join
\n# This ensures the message appears after the join message
\n# default: 1000 (1 second)
\nnotify-delay: 1000<\/p>\n
\n# Customize all messages sent by the plugin
\n# Available placeholders:
\n# {prefix} – The prefix defined above
\n# {player} – The player’s username
\n# {referrer} – The referrer’s username
\n# {claimer} – The claimer’s username
\n# {max-age} – The max age in seconds
\n# {max-age-hours} – The max age in hours
\n# {max-referrals} – The max referrals limit
\n# {hours} – Hours remaining (for time-remaining message)
\n# {minutes} – Minutes remaining (for time-remaining message)
\n# {value} – Generic value placeholder
\nmessages:
\n # Command messages
\n player-only: “&cThis command can only be used by players.”
\n no-permission: “&cYou do not have permission to use this command.”<\/p>\n
\n refer-usage: “&cUsage: \/refer
\n refer-success: “{prefix} &aYou have been referred by {referrer}!”
\n already-referred: “{prefix} &cYou have already set your referrer!”
\n cannot-refer-self: “{prefix} &cYou cannot refer yourself!”
\n referrer-not-joined: “{prefix} &cThe player ‘{referrer}’ has not joined the server before!”
\n account-too-old: “{prefix} &cYou cannot set a referrer because your account is too old!”
\n account-too-old-details: “&cMaximum age: {max-age} seconds ({max-age-hours} hours)”
\n circular-referral-blocked: “{prefix} &cCircular referrals are not allowed! {referrer} was referred by you.”
\n max-referrals-reached: “{prefix} &cThe player ‘{referrer}’ has reached the maximum number of referrals!”<\/p>\n
\n refer-explanation-header: “{prefix} &eReferral System”
\n refer-explanation-line1: “&eIf someone referred you to this server, use this command to give them credit!”
\n refer-explanation-usage: “&eUsage: &a\/refer
\n refer-explanation-current: “&aYou were referred by: &f{referrer}”
\n refer-explanation-time-remaining: “&eYou have &a{hours} hours and {minutes} minutes &eto claim your referral.”
\n refer-explanation-expired: “&cYour account is too old to claim a referral.”
\n refer-explanation-no-limit: “&eYou can claim your referral at any time!”<\/p>\n
\n notify-line1: “{prefix} &eYou haven’t set who referred you yet!”
\n notify-line2: “&eUse &a\/refer
\n help-header: “{prefix} &eReferral Plugin Commands:”
\n help-refer: “&a\/refer
\n help-referral-help: “&a\/referral help &7- Show this help message”
\n help-referral-config: “&a\/referral config &7- View current configuration”
\n help-referral-reload: “&a\/referral reload &7- Reload the plugin configuration”<\/p>\n
\n referral-usage: “&cUsage: \/referral
\n referral-unknown-subcommand: “&cUnknown subcommand. Use &e\/referral help &cfor available commands.”
\n reload-start: “{prefix} &eReloading referral configuration…”
\n reload-complete: “{prefix} &aReferral configuration reloaded.”<\/p>\n
\n config-header: “{prefix} &eCurrent Referral Configuration:”
\n config-circular: “&eCircular referrals: &f{value}”
\n config-max-referrals: “&eMax Referrals: &f{value}”
\n config-max-age: “&eMax Age: &f{value}”
\n config-referree-joined: “&eReferree Joined Requirement: &f{value}”
\n config-notify-on-join: “&eNotify on Join: &f{value}”
\n config-store-offline: “&eStore Rewards if Offline: &f{value}”<\/p>\n
\n# Rewards to give to the referrer and referree when a referral is claimed.
\nrewards:
\n # Claimer is the player who ran \/refer
\n claimer:
\n # Commands to run as console when a referral is claimed
\n # {player} is replaced with the claimer’s username
\n commands:
\n – “give {player} diamond 5”
\n # Messages to send to the claimer when a referral is claimed
\n messages:
\n – “&aYou have received 5 diamonds for being referred!”
\n # The player who referred the new player, this is the
\n referrer:
\n # Store if offline means if the referrer is offline when the referral is claimed, the commands and messages will run\/send when they next join
\n # default: true
\n store-if-offline: true
\n # Commands to run as console when a referral is claimed
\n # {player} is replaced with the referrer’s username
\n commands:
\n – “give {player} emerald 10”
\n # Messages to send to the referrer when a referral is claimed
\n # {claimer} is replaced with the claimer’s username
\n messages:
\n – “&aYou have received 10 emeralds for referring {claimer}!”<\/p>\n
\n # These are given to the referrer when they reach a certain number of referrals
\n # Milestones are only triggered once per milestone
\n # Available placeholders: {player}, {milestone}, {total}
\n milestones:
\n # Enable or disable milestone rewards
\n # default: true
\n enabled: true<\/p>\n
\n # The key (5, 10, 17, 25, etc.) is the number of referrals needed
\n 5:
\n commands:
\n – “give {player} diamond_block 1”
\n messages:
\n – “&6&lMILESTONE REACHED!”
\n – “&eYou have referred &a{total} &eplayers!”
\n – “&aYou received 1 Diamond Block!”
\n 10:
\n commands:
\n – “give {player} emerald_block 2”
\n messages:
\n – “&6&lMILESTONE REACHED!”
\n – “&eYou have referred &a{total} &eplayers!”
\n – “&aYou received 2 Emerald Blocks!”<\/p>\n
\n# Enable or disable bStats metrics collection
\n# This helps me understand how the plugin is being used
\n# default: true
\nbstats: true<\/p>\n
\n# Available placeholders (requires PlaceholderAPI):
\n# %referral_referred_by% – Username of who referred the player (or “None”)
\n# %referral_has_referrer% – “true” or “false”
\n# %referral_total_referrals% – Number of players this player has referred
\n# %referral_first_join% – Timestamp of first join (or “Unknown”)
\n# %referral_account_age% – Account age in seconds (or “Unknown”)
\n# %referral_account_age_hours% – Account age in hours (or “Unknown”)
\n# %referral_can_claim% – “true” or “false” if player can claim a referral
\n# %referral_time_remaining% – Seconds until referral claim expires (“Unlimited”, “Expired”, or seconds)
\n# %referral_time_remaining_hours% – Hours until referral claim expires (“Unlimited”, “Expired”, or hours)
\n# %referral_next_milestone% – Next milestone the player will reach (or “None”\/”Disabled”)
\n# %referral_referrals_until_next% – How many more referrals until next milestone (or “None”\/”Disabled”)<\/p>\n
\nIf you have PlaceholderAPI installed, you can use the following placeholders:
\n|Placeholder|Description|
\n|—–|—–|
\n|`%referral_referred_by%`|Who referred the player, “None” if not referred|
\n|`%referral_has_referrer%`|Does the player have a referrer, true\/false|
\n|`%referral_total_referrals%`|How many players has this player referred|
\n|`%referral_first_join%`|Timestamp in unix millis that the player first joined since the plugin has been installed|
\n|`%referral_account_age%`|Seconds since the player joined for the first time|
\n|`%referral_account_age_hours%`|Hours since the player joined for the first time|
\n|`%referral_can_claim%`|Can the player still claim a referral, checks if they have already been referred, and if they have joined too long ago|
\n|`%referral_time_remaining%`|Seconds until they can no longer claim a referral, or “Unlimited”, or “Expired”|
\n|`%referral_time_remaining_hours%`|How many hours are left until they can’t claim a referral, or “Unlimited”, or “Expired”|
\n|`%referral_next_milestone%`|How many referrals they need to have in total until the next milestone|
\n|`%referral_referrals_until_next%`|How many referrals they need until they get the next milestone|<\/p>\n
\nReward players for inviting more players, for example, give a bonus reward for the 5th referral, or for the 50th<\/p>\n
\nThere are only 2 useful permissions
\n1. `referral.use` – Allows players to run \/refer
\n2. `referral.admin` – Allows for `\/referral reload` and `\/referral config`, defaults to OP<\/p>\n
\n|Command|Description|Permission|Default|
\n|—–|—–|—–|—-|
\n|`\/refer
\n|`\/referral reload`|Reloads the config|`referral.reload`\/`referral.admin`|Defaults to OP|
\n|`\/referral config`|Shows some of the config values, mainly for debugging|`referral.config`\/`referral.admin`|Defaults to OP|<\/p>\n
\nNeed help with the plugin? Send a message to me on discord, my username is `editid`.<\/p>\n","protected":false},"excerpt":{"rendered":"