Voucher files

Each file in plugins/Claimo/vouchers/ defines one voucher. The file name (without .yml) is the code players redeem. Add a code by dropping in a new file, then run /code reload.

A complete example

plugins/Claimo/vouchers/test.yml

# vouchers/test.yml  →  redeemed with /code test

# One command (string) or several (list). A leading "/" is optional.
# %player% is replaced with the player's name. If PlaceholderAPI is installed,
# any other %placeholder% (e.g. %player_uuid%, %vault_eco_balance%) is resolved too.
cmd: "lp user %player% parent addtemp vip 7d"
# Optional standalone command to redeem this code, e.g. /testget (same as /code test).
# Registered on server (re)start. Omit for none.
redeem-command: testget
# Run as console (true) or as the player (false). Default: true.
console: true
# Hide from the GUI and tab-completion (still redeemable by code). Default: false.
hide: false
# Optional expiry as a human-friendly duration: s, m, h, d, w — e.g. 500s, 10m,
# 5d, 10w, or combined 1d12h. Counted from `created` if present, otherwise from
# the file's last-modified time. Omit for a code that never expires.
expires: 30d
# Optional redemption limit. Omit for unlimited.
limit:
  mode: per-player
  amount: 1
# All requirements must pass before the code is redeemable. Optional.
requirements:
  - type: blocks_mined
    amount: 100
# Optional physical item form — give with /code give, redeem by right-clicking.
item:
  material: PAPER
  name: "<aqua>Test voucher"
  lore:
    - "<gray>Right-click to redeem."

Fields

cmd — the command(s) to run

The heart of a voucher. Accepts a single string or a list of strings; a leading / is optional.

Single command

cmd: "give %player% diamond 5"

Multiple commands

cmd:
  - "give %player% diamond 5"
  - "eco give %player% 100"
  - "broadcast %player% just redeemed a reward!"

• %player% is replaced with the redeeming player’s name.
• With PlaceholderAPI installed, any other %placeholder% (e.g. %player_uuid%, %vault_eco_balance%) is resolved too.
• A line of the form action:<name> <args> runs a reward action registered by an addon instead of dispatching a command.

random — pick one command instead of all

default: false — with random: true, one entry from cmd is picked at random per redeem (instead of running all of them). The pick is uniform unless entries declare a chance weight:

random: true
cmd:
  - command: "give %player% diamond 5"
    chance: 10                          # 10 / (10+90) = 10%
  - command: "give %player% dirt 1"
    chance: 90

Weights are relative — they don’t have to add up to 100. Plain string entries and weighted map entries can be mixed; strings count as chance: 1.

console — who runs the command

default: true — run the command as console (true) or as the player (false).

console: false   # runs as the player, with their permissions

hide — keep it out of listings

default: false — when true, the code is excluded from the GUI and tab-completion but stays redeemable by typing it exactly. Ideal for secret or event codes.

redeem-command — a shortcut command

Optional. Registers a standalone command that redeems this code directly, so players can run /testget instead of /code test. A leading / is optional; only the first word is used.

redeem-command: testget

The command behaves exactly like /code <name> — same permission (claimo.use), requirements, limits and messages.

Takes effect on (re)start

Standalone commands are registered while the server builds its command tree, so a new or changed redeem-command only becomes active after a server restart (or a full /reload) — /code reload alone won’t register it. A command that clashes with another Claimo command (the main command, the dialog command, claimo, or another voucher’s) is skipped with a console warning.

expires — a time limit

A human-friendly duration, omit for a code that never expires.

Unit	Meaning	Example
s	seconds	500s
m	minutes	10m
h	hours	12h
d	days	5d
w	weeks	10w

Units combine: 1d12h means one and a half days.

What is it counted from?

Expiry counts from the created timestamp (epoch millis, written by the in-game creator) when present, otherwise from the file’s last-modified time.

starts — an activation time

Optional. Before this moment the code behaves like a hidden one — it’s out of the GUI and tab-completion, and redeeming answers with a “starts in …” message. Accepts either a duration counted the same way as expires (from created, else the file’s last-modified time) or an absolute local date/time:

starts: "2026-08-15 18:00"   # or a date: "2026-08-15", or a duration: 2d
expires: 30d                 # combine both for a from–to window

cooldown — a per-player delay

Optional. Each player must wait this long between redemptions — ideal for daily/weekly codes. Same duration units as expires. Unlike limit, it doesn’t cap total uses.

cooldown: 1d    # a daily code

Note

Cooldowns are stored on the player, so they survive restarts and work independently of the usage database. /code purge also clears the cooldowns of deleted codes for online players.

price — a Vault cost

Optional. The player is charged this amount (via Vault) when the code is redeemed. Players who can’t afford it get a not-enough-money message; the withdrawal happens only after every other check (limits, cooldown, requirements) has passed.

price: 100.0

Redeeming a priced code always asks for confirmation first: on 1.21.7+ a confirmation dialog opens, on older servers the player is asked to redeem the code again within 10 seconds — so a stray right-click on a voucher item never charges anyone by accident.

Needs a Vault economy

Requires Vault plus an economy provider (EssentialsX, CMI, …). Without one, a priced code refuses to redeem rather than handing out the reward for free.

effects — a celebration on redeem

Optional. Fireworks and/or a particle shape played at the player when the redeem succeeds.

effects:
  fireworks: 2       # rockets launched at the player (0-10)
  particle: FLAME    # any Bukkit particle name, omit for none
  shape: helix       # burst (default), circle, sphere or helix

An unknown particle or shape logs a console warning and is skipped — the redeem itself is never blocked by a bad effect.

limit — redemption caps

Omit for unlimited redemptions.

per-player

Each player may redeem amount times — no shared pool.

limit:
  mode: per-player
  amount: 1

global

A shared pool of amount one-time redemptions: the first amount distinct players each redeem once, then the code is gone.

limit:
  mode: global
  amount: 50

amount defaults to 1.

No double-spend

Global pools are re-checked authoritatively inside a single-threaded scheduler block on redeem, so two players hitting the last slot at once can’t both win it.

requirements — gates that must pass

An optional list of checks; all must pass before the code redeems. Each entry has a type and that type’s own parameters.

requirements:
  - type: playtime
    duration: 1h
  - type: account_age
    duration: 7d

See Requirements for the full catalogue of built-in types and their parameters.

item — a physical voucher item

Optional. Gives the code an item form: admins hand it out with /code give <players> <code> [amount] and players redeem it by right-clicking (one item is consumed per successful redeem — requirements and limits still apply).

Every key inside item is optional; an empty item: section falls back to plain paper.

item:
  material: PAPER                  # any Bukkit material (default: PAPER)
  name: "<aqua>Test voucher"       # MiniMessage; <voucher> resolves to the code
  lore:
    - "<gray>Right-click to redeem."
  custom_model_data: 1             # single value — works on every version
  item_model: "minecraft:paper"    # resource key, 1.21.2+ servers only

On 1.21.4+ servers, custom_model_data also accepts the component form with lists (a bare list is treated as floats):

item:
  custom_model_data:
    floats: [1.0]
    flags: [true]
    strings: ["ruby"]
    colors: ["#FF0000"]            # hex colors

Instead of the settings above, the item can come from another item plugin — set exactly one of these to that plugin’s item id (name, lore and model keys still apply on top if set):

item:
  nexo_item: item_id     # Nexo
  # ia_item: item_id     # ItemsAdder
  # ce_item: item_id     # CraftEngine

If the referenced plugin or item id can’t be resolved, Claimo logs a warning and falls back to material (or paper).

Items update themselves

Voucher items carry a fingerprint of their item section. After you edit it and run /code reload, outdated copies held by players are rebuilt automatically — on join, when they open an inventory, or when the item is dropped.

Reloading

After editing any voucher file, apply your changes:

/code reload