Cashback

Cashback

Vault cashback cycles for Paper 1.20.6–26.3 and Purpur 1.21.11 / 26.3 · Java 21+

Players spend money at your shop to fill a progress bar. When the bar is full, cashback becomes ACTIVE, and a percentage of their next purchases is automatically paid back through Vault. When the quota runs out, the cycle resets and filling starts again.

How a Cycle Works

1. FILL — Purchases add value to the progress bar. These purchases do not pay cashback.
2. ACTIVATE — At 100%, the progress bar unlocks a cashback quota.
3. PAYOUT — Every purchase while ACTIVE pays back the configured percentage, 30% by default.
4. RESET — When the quota reaches zero, the cycle starts again.

Features

• Encourage repeat purchases without coupons, ranks, or manual giveaways.
• Crash-safe payouts — Every payout is claimed in the database before the Vault deposit, preventing duplicate payments after a crash. Use /cb admin recover to settle anything left over. Payouts that may already have been paid are blocked until you confirm them with force.
• No double counting — One purchase equals one payout, even if a shop plugin fires several events.
• Large purchases count in full — A purchase worth several cycles is calculated exactly and is never truncated.
• Per-rank targets and cashback rates through permission nodes, with LuckPerms support.
• Optional carry-over — Value that passes a stage limit can continue into the next stage instead of being discarded.

Requirements

• Paper 1.20.6–26.3 or Purpur 1.21.11 / 26.2
• Java 21+
• Vault and a Vault-compatible economy plugin
• Optional: EconomyShopGUI (Free or Premium), UltimateShop 3.6.3+, and PlaceholderAPI

Platform support: This is a Paper plugin. It does not run on Spigot or CraftBukkit because it uses the Paper API and the plugin.yml libraries loader. Folia is not supported.

Installation

1. Drop Cashback.jar into the server's /plugins folder and restart the server.
2. Make sure Vault and an economy plugin are installed.
3. Edit plugins/Cashback/config.yml if you want to use different targets or rates.
4. Run /cb admin health to see which shop adapters were detected.
5. Buy something in your shop and check /cb status.

Commands

Command · Description
/cb · Show your cashback progress bar.
/cb status · Show your progress bar with quota details.
/cb history · Show your last 5 payouts.
/cb version · Show the plugin version, server, Java version, adapters, and storage.
/cb admin health · Show the status of shop adapters.
/cb admin inspect · Inspect a player's cycle state and rank.
/cb admin reset · Reset a player's cycle.
/cb admin recover [force] · Settle payouts left pending by a crash.
/cb admin reload · Reload the configuration and language files.

Permissions

Permission · Default · Description
cashback.use · true · Use /cb, /cb status, and /cb history.
cashback.admin · op · Access all admin commands.
cashback.admin.help · — · Access /cb help.
cashback.admin.version · — · Access /cb version.
cashback.admin.reload · — · Access /cb admin reload.
cashback.admin.health · — · Access /cb admin health.
cashback.admin.inspect · — · Access /cb admin inspect .
cashback.admin.reset · — · Access /cb admin reset .
cashback.admin.recover · — · Access /cb admin recover [force].
cashback.rank. · — · Set the target and cashback rate for a rank. Configure ranks under ranks.groups.

Shop Integrations

• EconomyShopGUI — Free and Premium versions are supported.
• UltimateShop — Version 3.6.3 or newer. Only the Vault portion of a price counts toward cashback.
• Purchases paid with items, EXP, PlayerPoints, or other economies do not produce cashback.
• If an unknown shop plugin is detected, Cashback remains idle instead of guessing.

Configuration Example

config.yml

config-version: 4

language:
default: en
fallback: en
directory: lang

cycle:
fill-target: 500000.0 # shop purchases needed to reach 100%
cashback-target: 500000.0 # purchase value that earns cashback while ACTIVE
cashback-rate: 30.0 # percent paid back (0-100)
carry-over: false # true: value beyond a stage limit continues into the next stage

ranks:
enabled: false
groups:
vip:
permission: cashback.rank.vip
priority: 10
cashback-rate: 35.0
mvp:
permission: cashback.rank.mvp
priority: 20
cashback-rate: 40.0
fill-target: 400000.0
cashback-target: 600000.0

notifications:
activated:
action-bar: true
chat: true
sound:
enabled: true
name: "minecraft:block.beacon.activate"
volume: 1.0
pitch: 1.2
deactivated:
action-bar: true
chat: true
sound:
enabled: true
name: "minecraft:block.beacon.deactivate"
volume: 1.0
pitch: 1.0
earned:
chat: true

integrations: # changing these needs a restart
economyshopgui:
enabled: true
ultimateshop:
enabled: true

history:
retention-days: 365 # finished entries older than this are deleted daily; 0 = keep forever

metrics:
enabled: true

Troubleshooting

Common issues

“No Vault economy provider registered yet”

Vault is installed, but no economy plugin has registered a provider. Install an economy plugin such as EssentialsX or CMI, or check that it loaded before Cashback.

Cashback is not paid

Check /cb admin health for the adapter names. If it shows none, the shop plugin may be missing or its API class may not have been found. Also confirm that the purchase was paid with Vault money, not items or EXP.

Duplicate or missing payouts after a crash

Run /cb admin recover and compare the result with your economy log. Rows that may already have been paid are reported as blocked. Only use /cb admin recover force after checking the economy log.

Players keep progress but receive no payout

This is the FILLING phase by design. Cashback is paid only while the cycle is ACTIVE.

Languages

English and Indonesian are included. Language files are located in plugins/Cashback/lang and are never overwritten. New keys are added automatically when the plugin is updated.

Support

Please post in the discussion tab with the following information:

• Server software and version
• Cashback version from /cb version
• Shop plugin and version
• Relevant console lines