# Referral Reward

The player must achieve a given use of his referral.\
Referrals work through the player's nick. Anyone can use the `/referral create` command or the `[CREATE_REFERRAL]` action in the menu to create their. Players also need to have `ultimaterewards.referral.create` permission to be able create referral.\
\
Referrals can then be activated via the `/referral apply <player>` command or via the `[APPLY_REFERRAL]` action used in menu.\
\
It is also possible to limit when a player can create or apply a referral, more [here](https://revivalo.gitbook.io/ultimaterewards/configuration/rewards/features/reward-requirements#checkers-for-affiliates).

* `required-uses` \[number] - the number of referral uses required to achieve this reward.

{% hint style="info" %}
The rewards a player gets after applying a referral are set in **referrals.yml**
{% endhint %}

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: referral_reward
#
# Reward tag
#
tag: Referral Reward
#
# Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleReferralReward
#
# Required referred players to achieve this reward.
#
required-uses: 5
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONE ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE WILL BE REPLACED BY STONE IF INVALID NAME IS IN USE.
#
# When the player achieves the required number of referred players,
# this version of the reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a#1 &lREFERRAL"
available-lore:
  - '&8Referral reward unlocked'
  - '&8upon activation by 5 players.'
  - ' '
  - '&7Contains:'
  - '&e ➪ 16x XP Bottle'
  - ' '
  - '&b► Click to claim reward'
#
# Whereas the player doesn't have enough referred players,
# this version of the reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&4#1 &lREFERRAL"
unavailable-lore:
  - ' '
  - '&7Contains:'
  - '&7 ➪ 16x XP Bottle'
  - ' '
  - '&4► To unlock, you need to invite'
  - '&4  %players% more players!'
#
# When the player has already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&7#1 &lREFERRAL"
claimed-lore:
  - ' '
  - '&7Contains:'
  - '&7 &m➪ 16x XP Bottle'
  - ' '
  - '&7 Already claimed'
  - '&7 for %uses% referrals!'
#
# When the player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c#1 &lREFERRAL"
no-permission-lore:
  - '&c ✕ Locked, requires'
  - '&c   %permission% permission'
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions can be found at
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from the randoms.yml file and use them in commands.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% experience_bottle 16'
  - '[console] say %player% claimed his %type% reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ultimaterewards.athelion.eu/configuration/rewards/reward-types/referral-reward.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.