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

Permissions

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-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

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