Requirements

A voucher’s requirements: list holds checks that all must pass before the code is redeemable. When a redeem fails, Claimo prints the whole checklist — met lines and unmet lines — so the player knows exactly what’s left to do.

vouchers/reward.yml

requirements:
  - type: playtime
    seconds: 3600
  - type: account_age
    days: 7

Lazily resolved

Requirements are resolved on each redeem, so a type registered by an addon after Claimo already loaded its config still works — the normal case for addons.

Built-in types

blocks_mined

Blocks the player has broken.

playtime

Total time on the server.

messages_sent

Qualifying chat messages sent.

account_age

Days since first join.

permission

Permission nodes held / not held.

rank

Vault permission groups.

custom

Compare any PlaceholderAPI value.

blocks_mined

Player has broken at least amount blocks — tracked by Claimo, persisting across restarts.

Parameter	Required	Meaning
amount	✅	Minimum blocks broken.
whitelist	optional	Only these material types are counted.
blacklist	optional	These material types are never counted.

- type: blocks_mined
  amount: 100
  # Only diamond ore counts toward this one.
  whitelist:
    - DIAMOND_ORE
    - DEEPSLATE_DIAMOND_ORE
  # blacklist:
  #   - STONE

Material names are Bukkit constants (e.g. DIAMOND_ORE).

How the counter stays small

Claimo keeps a running total of blocks mined per player in their PDC. A per-material counter is only kept for materials that appear in some voucher’s whitelist/blacklist — every other block just bumps the total. The total is always exact; a material’s per-type count begins accruing from when it first appears in the config.

playtime

Player’s total time on the server is at least duration (the vanilla play-time statistic). duration accepts a friendly string such as 1h 30m, 5d or 2w; a bare number is read as seconds. The legacy seconds key still works.

- type: playtime
  duration: 1h 30m

messages_sent

Player has sent at least amount qualifying chat messages.

Parameter	Default	Meaning
amount	—	Minimum qualifying messages.
min-length	10	A message must be at least this many characters.
delay-seconds	20	At least this long must pass since the last counted message.

- type: messages_sent
  amount: 25
  min-length: 10
  delay-seconds: 20

Anti-spam by design

The min-length and delay-seconds rules stop players farming the requirement with short spam. Each distinct (min-length, delay-seconds) pair is tracked separately, so different vouchers can use different rules without interfering.

account_age

Player’s account first joined the server at least duration ago — gates rewards away from brand-new accounts and alts. duration accepts a friendly string such as 7d or 2w; the legacy days number still works.

- type: account_age
  duration: 7d

permission

Player must hold at least one of permissions and none of denied-permissions.

- type: permission
  permissions: [claimo.vip, claimo.mvp]   # must have at least one
  denied-permissions: [claimo.redeemed]   # must have none

• Omit permissions for no positive requirement.
• Use denied-permissions to lock a code away from players who already hold a node.
• Both accept a YAML list or a comma-separated string; the singular permission / denied-permission keys also work.

rank

Same shape as permission, but for permission groups resolved via Vault.

- type: rank
  denied-ranks: [admin, owner]   # staff can't redeem this one

Needs a Vault provider

Requires a Vault provider such as LuckPerms. Without one, a positive ranks requirement can’t pass. The singular rank / denied-rank keys also work.

custom

Resolves a placeholder via PlaceholderAPI and compares it to value. Lets you gate on anything PAPI exposes — economy, level, stats — without a dedicated requirement.

Parameter	Meaning
placeholder	The left-hand side — resolved through PlaceholderAPI for the player.
operator	One of == != contains regex >= <= > <.
value	The right-hand side — also resolved through PlaceholderAPI, so a literal (1000, true) and another placeholder both work.

- type: custom
  placeholder: "%vault_eco_balance%"
  operator: ">="
  value: "1000"

# Both sides accept placeholders — literals and placeholders mix freely:
- type: custom
  placeholder: "%superiorskyblock_has_island%"
  operator: "=="
  value: "true"
- type: custom
  placeholder: "%player_level%"
  operator: ">="
  value: "%someplugin_required_level%"

Note

Numeric operators (>= <= > <) parse both sides as numbers. Needs PlaceholderAPI installed.

Its requirement-custom message (in messages.yml) can use these placeholders, so you can phrase the checklist line however you like:

Placeholder	Value
<placeholder>	The raw placeholder string as configured, e.g. %vault_eco_balance%.
<placeholder_pretty>	The placeholder with % stripped and _ turned into spaces, e.g. vault eco balance.
<placeholder_parsed>	The placeholder resolved to the player’s current value.
<operator>	The configured operator.
<value>	The raw value string as configured.
<value_parsed>	The value resolved to the player’s current value (same as <value> for literals).

messages.yml

requirement-custom: "<placeholder_pretty>: <placeholder_parsed> (need <operator> <value>)"

Operators in YAML and MiniMessage

> on its own is a YAML block indicator, so quote it: operator: ">". In the message, insert the operator with <operator>; Claimo inserts it literally, so < and > show up correctly instead of being read as MiniMessage tags.

Logical groups: any, all, not

By default every entry in requirements: must pass. Group entries let you express OR and NOT logic — a group counts as a single requirement whose children decide its outcome:

• any: — satisfied when at least one child passes.
• all: — satisfied when every child passes (useful inside any).
• not: — satisfied when no child passes.

(VIP or Premium) and 2h of playtime

requirements:
  - any:
      - type: permission
        permission: claimo.vip
      - type: rank
        rank: premium
  - type: playtime
    duration: 2h

Groups nest freely — an any can contain an all, and so on. In the redeem checklist a group prints as one line built from the requirement-group-any / -all / -not message, with <requirements> holding the children’s descriptions.

File-only

Groups are configured in voucher files; the in-game creator edits flat requirements only and leaves existing groups untouched.

The redeem checklist

When a redeem fails, the whole requirement checklist is printed. Met lines use the requirement-met message, unmet lines use requirement-unmet, each wrapping the requirement’s own <description>. Customise those in messages.yml.

Adding your own

None of these fit? Requirement types are a public API — register your own (e.g. a social-media follow check) from an addon. See Custom requirements.