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 checked together, off the main thread, before any reward runs.

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.