Voucher Reference

A voucher is one plugins/ProVouchers/vouchers/<id>.yml file. This page documents the voucher-specific fields. The shared building blocks have their own pages: Items, Conditions, and Rewards.

After editing, run /voucher reload. Errors are reported per file with the key and reason.

Full example

vouchers/crate_key.yml

id: crate_key
display-name: "<gradient:#FFD700:#FF4500>Crate Key</gradient>"
item:
  material: TRIPWIRE_HOOK
  glow: true
lore:
  - "<gray>Right-click to open a crate"
  - ""
  - "<dark_gray>Season 1"
unredeemable: false
owner-only: false
has-argument: false
cooldown: 0
expiry: ""
conditions:
  - type: permission
    permission: "provouchers.use.crate_key"
rewards:
  - "command: crates give %player% vote 1"
  - "message: <green>Enjoy your crate key!"
random-rewards:
  - weight: 80
    rewards:
      - "item: GOLD_INGOT {random:1-3}"
  - weight: 20
    rewards:
      - "item: DIAMOND 1"
      - "broadcast: <gold>%player% <yellow>hit the rare reward!"

Identity

Key	Type	Default	Notes
`id`	string	file name	The unique voucher id. Lookups are case-insensitive.
`display-name`	MiniMessage	file name	The item name. Omit it to keep a custom provider item's own name.
`lore`	list of MiniMessage	empty	The item description lines.

See Items for the item: section (material, custom provider items, custom model data, glow) and Text and Placeholders for what you can put in display-name and lore.

Flags

Key	Type	Default	What it does
`unredeemable`	boolean	`false`	A display-only item that cannot be redeemed (useful for showcases or collectibles).
`owner-only`	boolean	`false`	Only the player it was given to may redeem it. The owner is stamped at give time.
`has-argument`	boolean	`false`	Reserved for a future parametric form. Codes already accept an argument via `/voucher redeem <code> <arg>`.

Owner-only stamps the recipient's UUID onto the item when it is given. A different player holding the same item is rejected. provouchers.bypass.owner overrides this. Items given before owner-only was enabled (with no owner stamp) are not restricted.

Cooldown

cooldown: 86400   # seconds; 24 hours

A per-player, per-voucher cooldown in seconds. 0 (the default) means no cooldown. provouchers.bypass.cooldown ignores it.

Cooldowns are persisted to the database and reloaded when a player joins, so they survive restarts. On a network sharing one database (see Storage), a cooldown applies across all servers.

Expiry

expiry: ""                       # never expires (default)
expiry: "2026-12-31T23:59:59Z"   # absolute: a fixed moment (ISO-8601)
expiry: "30d"                    # relative: 30 days after the item was given

expiry accepts three forms:

Empty means the voucher never expires.
An ISO-8601 instant is a fixed moment in time, the same for every copy.
A relative duration (30d, 12h, 90m, 45s) is measured from the moment the item was given, so a "30d" voucher given today stops working in 30 days.

The give time is stamped onto each item, so relative expiry is per-item. Bad expiry values are caught by /voucher reload, not at redeem time.

For codes there is no per-item give time, so prefer an absolute ISO instant. A relative duration on a code is measured from when it is checked and will not expire as you expect.

Rewards and conditions

These are shared with codes and have dedicated pages:

Conditions: who can redeem, and where (conditions:).
Rewards: what they get (rewards: and random-rewards:).

Giving vouchers

/voucher give <id> [amount] [player]
/voucher giveall <id> [amount]

See Commands and Permissions for the full command tree.