Sales, promo codes and referrals

Run timed sales, hand out promo codes with use limits, and reward players who bring in buyers.

All three live in promotions.yml and are switched on per entry. A sale lowers the price for everyone for a while. A promo code is typed by the player at checkout. A referral code is a player's own code that gives the buyer a discount and rewards the player who shared it.

A typed code is checked against promo codes first and referral codes second. Any failure shows the same reason so codes cannot be guessed, and five wrong codes in a minute make the player wait.

Sales

sales:
  summer:
    enabled: true
    display-name: "<gradient:#ff6a00:#ffb000><bold>Summer Sale</bold></gradient>"
    type: percent
    value: 20
    starts: "2026-12-20T00:00:00"
    ends: "2026-12-31T23:59:59"
    applies-to: []
    allow-codes: true

A sale is active while it is enabled and the server time is between starts and ends. Leave either out for no limit on that side.
type: percent takes value percent off. type: fixed takes value off, in your main currency.
applies-to lists categories (ranks) or single items (ranks/vip). Empty means everything.
When several sales apply to one item, only the one that saves the most is used.
allow-codes: false stops a promo or referral code being used on top of this sale.
Menus show the sale price through <price> and the old price through <old-price> in lore. See Category files.

codes:
  WELCOME10:
    enabled: true
    type: percent
    value: 10
    max-uses: 500
    per-player: 1
    expires: "2026-12-31T23:59:59"
    applies-to: []

Players type the code in the checkout dialog, or save it first with /store code <code> (useful for players on the chest menu, which has no code field).
Codes are not case sensitive and can use letters, digits, _ and -, up to 32 characters.
max-uses caps the total across all players, per-player caps each buyer. Leave either out for no limit.
A use counts while its order is completed or still waiting for payment. Failed, expired, refunded and disputed orders give the use back, so a code can never be oversold.
A code that does not exist, is off, has expired, is used up or does not apply to the item always gives the same message, "That code is not valid for this purchase", so players cannot guess which codes exist.
Five wrong codes within a minute and the player has to wait.

Referrals

referrals:
  enabled: true
  first-purchase-only: true
  buyer-discount:
    type: percent
    value: 5
  referrer-commands:
    - "give %player% diamond 1"
  referrer-amount: 0

The player gets a code

/store referral shows the player's own referral code (8 characters, made on first use) and how many times it was used.

A friend uses it

The friend types it in the same field as a promo code. Promo codes are checked first, then referral codes. One code per order, and a player cannot use their own.

Both are rewarded

The buyer gets buyer-discount. When that order completes, the referrer gets referrer-commands (with %player% as the referrer and %buyer% as the buyer) and referrer-amount through Vault, once per order, even if they are offline.

With first-purchase-only: true, only a buyer with no earlier completed order can use a referral code.

A referrer's reward is not taken back if the order is later refunded or disputed. The refund notice tells staff that a referral reward was paid, so they can decide.

All the keys are listed on the Promotions file page.