Developer API

ProVouchers ships a small, interface-only API (so.alaz.provouchers.api) for other plugins: a service to query and give vouchers, and events to veto or observe redemptions. It is available since 0.4.0 and, while ProVouchers is pre-1.0, may change between minor versions.

Depend on the API

Add the alazso repository and the provouchers-api artifact, compile-time only. The runtime classes ship inside the installed ProVouchers plugin, so you bundle nothing.

repositories {
    maven("https://repo.alaz.so/releases") { name = "alazso" }
}

dependencies {
    compileOnly("so.alaz.provouchers:provouchers-api:0.4.0")
}

Declare ProVouchers as a dependency in your paper-plugin.yml so it loads first:

dependencies:
  server:
    ProVouchers:
      load: BEFORE
      required: true   # or false for a soft integration

The VoucherService

Obtain it from Bukkit's services manager once ProVouchers has enabled:

import so.alaz.provouchers.api.VoucherService;

VoucherService vouchers = getServer().getServicesManager().load(VoucherService.class);
if (vouchers != null) {
    vouchers.getVoucher("crate_key").ifPresent(v ->
        getLogger().info("Cooldown: " + v.cooldownSeconds() + "s"));

    vouchers.give(player, "crate_key", 1);   // async, Folia-safe
}

Method	Returns
`getVoucher(id)`	`Optional<Voucher>`
`voucherIds()`	`List<String>`
`getCode(input)`	`Optional<VoucherCode>`
`voucherCount()` / `codeCount()`	`int`
`give(player, voucherId, amount)`	`boolean` (false if the id is unknown)

Voucher and VoucherCode are read-only views (id, display name, lore, flags, cooldown, expiry, use limits). They are implemented by ProVouchers and must not be implemented by consumers.

Events

All events live in so.alaz.provouchers.api.event and are standard Bukkit events, so you listen for them the usual way.

Veto a redemption

VoucherPreRedeemEvent and VoucherCodePreRedeemEvent are cancellable and fire before the redemption commits, after ProVouchers' own checks. Cancel one to veto:

@EventHandler
public void onPreRedeem(VoucherPreRedeemEvent event) {
    if (isFrozen(event.getPlayer())) {
        event.setCancelled(true);   // anti-cheat, spending limits, etc.
    }
}

Observe a redemption

VoucherRedeemEvent and VoucherCodeRedeemEvent fire after a successful redeem (item consumed, anti-dupe passed, rewards granted). They are not cancellable:

@EventHandler
public void onRedeem(VoucherRedeemEvent event) {
    getLogger().info(event.getPlayer().getName()
        + " redeemed " + event.getVoucher().id()
        + " (batch " + event.getBatchId() + ")");
}

Event	Cancellable	When
`VoucherPreRedeemEvent`	yes	before an item voucher is redeemed
`VoucherRedeemEvent`	no	after an item voucher is redeemed
`VoucherCodePreRedeemEvent`	yes	before a code is redeemed
`VoucherCodeRedeemEvent`	no	after a code is redeemed

These events fire on the redeeming player's region thread, not necessarily the global main thread. Keep handlers Folia-safe: schedule any cross-region work through your own scheduler rather than assuming the main thread.

Stability

The API is annotated with @ApiStatus.AvailableSince("0.4.0"), and the read-only types are @ApiStatus.NonExtendable. While ProVouchers is in the 0.x series the surface may change between minor releases; it stabilises at 1.0.0.