Code Reference

A code is one plugins/ProVouchers/codes/<id>.yml file. Players redeem it by typing /voucher redeem <code>. Codes share the Conditions and Rewards systems with vouchers; this page covers the fields that are specific to codes.

Full example

codes/launch_gift.yml

code: LAUNCH2026
case-sensitive: false
enabled: true
max-uses: 500
uses-per-player: 1
expiry: "2026-12-31T23:59:59Z"
conditions:
  - type: permission
    permission: "provouchers.redeem"
rewards:
  - "currency: give 1000"
  - "item: itemsadder:ax_wings_pack:phoenix_wings 1"
  - "message: <gradient:#FFD700:#FF4500>Thanks for joining at launch!</gradient>"
effects:
  sound: "minecraft:entity.player.levelup 1 1"

Fields

Key	Type	Default	Notes
`code`	string	file name	The literal text players type.
`case-sensitive`	boolean	`false`	When `false`, `LAUNCH2026` and `launch2026` both match.
`enabled`	boolean	`true`	Set `false` to keep the code loaded but refuse every redeem with `code.disabled`.
`max-uses`	integer	`-1`	Global redemption cap across all players. `-1` means unlimited.
`uses-per-player`	integer	`1`	How many times a single player may redeem it.
`expiry`	string	`""`	Use an absolute ISO-8601 instant (see the note below).
`conditions`	list	empty	See Conditions.
`rewards`	list	empty	See Rewards.
`random-rewards`	list	empty	Weighted "pick one" rewards.
`has-argument`	boolean	`false`	Accept a trailing argument, exposed to rewards as `%arg%`.
`effects`	map	empty	A sound and/or firework played to the redeemer on success. See Redeem effects.

Use limits

Codes have two independent limits, both backed by the database so they survive restarts:

uses-per-player caps how many times one player may redeem the code. With the default 1, each player may redeem it once.
max-uses caps the total redemptions across everyone. Set it to limit a giveaway to the first N claims; leave it at -1 for no global cap.

Both are reserved together in the database, off the main thread, before any reward runs, so players redeeming at the same moment (even on different servers sharing a database) cannot exceed either limit. If the player logs out before the reward is granted, the use is given back.

Arguments

With has-argument: true, players pass a value that rewards can use through the %arg% placeholder:

codes/referral.yml

code: REFER
has-argument: true
rewards:
  - "broadcast: <green>%player% was referred by %arg%!"
  - "currency: give 100"

/voucher redeem REFER Steve

The %arg% is substituted into rewards and messages before MiniMessage is rendered. See Rewards for the full placeholder list.

Redeem effects

Like vouchers, a code can play a sound and/or a firework to the player on a successful redeem:

effects:
  sound: "minecraft:entity.player.levelup 1 1"   # key [volume] [pitch]
  firework:
    colors: [ YELLOW, "#FF8A00" ]   # named colors or #RRGGBB hex
    fade: [ RED ]                   # optional fade colors
    type: BALL                      # BALL | BALL_LARGE | STAR | BURST | CREEPER
    power: 0                        # 0 detonates at the player, up to 2 to fly

The block is identical to a voucher's; see Redeem effects for the field details. The firework never deals damage.

Expiry

Unlike voucher items, a code has no per-item give time. Use an absolute ISO-8601 instant (2026-12-31T23:59:59Z) for code expiry. A relative duration (30d) is not measured from a meaningful start point for codes.

Tab completion

/voucher redeem does not currently suggest code names in tab completion (codes are often meant to be shared out of band, not discovered). Type the code exactly, honouring case-sensitive when it is set.