# PromoCode Mod \u2014 Minecraft Forge 1.16.5<\/p>\n
A complete promotional code system for Minecraft servers. Server administrators can create codes that reward players with items, with full control over quantities, limits, and expiration dates.<\/p>\n
—<\/p>\n
## Overview<\/p>\n
PromoCode Mod adds an intuitive in-game interface for redeeming promotional codes. Perfect for:
\n– \ud83c\udf81 **Starter rewards** for new players
\n– \ud83c\udf89 **Event bonuses** (seasonal, special occasions)
\n– \ud83c\udfc6 **Achievement rewards** (giveaways, contests)
\n– \ud83d\udc65 **Community perks** (Discord members, supporters)<\/p>\n
—<\/p>\n
## Key Features<\/p>\n
\u2705 **Simple GUI** \u2014 Players press `\/promo` and enter a code
\n\u2705 **Flexible rewards** \u2014 Multiple items per code, customisable quantities
\n\u2705 **Admin controls** \u2014 Create\/delete codes in-game using commands
\n\u2705 **Usage limits** \u2014 Set maximum redemptions or expiration dates
\n\u2705 **Anti-abuse** \u2014 Each player can claim each code only once
\n\u2705 **Statistics** \u2014 Track total items distributed and unique players
\n\u2705 **Offline-friendly** \u2014 Works perfectly on offline-mode servers
\n\u2705 **Auto-saves** \u2014 All data persisted to `promocodes_data.json`<\/p>\n
—<\/p>\n
## Installation<\/p>\n
### For Server Administrators<\/p>\n
1. Download the `.jar` file from ModRinth or CurseForge
\n2. Place it in your Forge 1.16.5 `mods\/` folder
\n3. Start the server \u2014 configuration files generate automatically
\n4. Edit `server_config\/promocodemod-server.toml` to add default codes (optional)
\n5. Restart the server<\/p>\n
### For Players<\/p>\n
The mod is server-side, so you only need it if your server uses it. It’ll be on the server’s mod list.<\/p>\n
—<\/p>\n
## Quick Start \u2014 Creating Your First Code<\/p>\n
### Via In-Game Command (Easiest)<\/p>\n
“`
\n\/promo create WELCOME minecraft:diamond 5
\n“`<\/p>\n
Now players can type `\/promo`, enter `WELCOME`, and get 5 diamonds!<\/p>\n
### Advanced: Multiple Items<\/p>\n
“`
\n\/promo create STARTER minecraft:diamond 3 minecraft:iron_sword 1 minecraft:bread 10 0 0
\n“`<\/p>\n
Players get: 3 diamonds, 1 iron sword, 10 bread. Unlimited uses, never expires.<\/p>\n
### Advanced: Limited Time Event<\/p>\n
“`
\n\/promo createraw HALLOWEEN:minecraft:pumpkin,20;minecraft:orange_dye,10|50|0
\n“`<\/p>\n
Only 50 total redemptions, never expires, includes 20 pumpkins and 10 orange dye.<\/p>\n
### Delete Old Codes<\/p>\n
“`
\n\/promo delete WELCOME
\n“`<\/p>\n
—<\/p>\n
## Complete Command Reference<\/p>\n
### Player Commands<\/p>\n
| Command | Purpose |
\n|———|———|
\n| `\/promo` | Open the redemption GUI |
\n| `\/promocode` | Same as `\/promo` |
\n| `\/promo help` | Display all available commands |<\/p>\n
### Administrator Commands (Op Level 2+)<\/p>\n
**Create Code:** **Delete Code:** **Show Help:** —<\/p>\n ## Parameters Explained<\/p>\n | Parameter | Value | Notes | ### Expiry Date Examples<\/p>\n Convert to Unix epoch using unixtimestamp.com:<\/p>\n | Date | Epoch | Set to `0` for no expiration.<\/p>\n —<\/p>\n ## Common Item IDs<\/p>\n “` **Tip:** Hover over items in Minecraft’s creative inventory to see their exact ID.<\/p>\n —<\/p>\n ## Configuration File<\/p>\n Edit `server_config\/promocodemod-server.toml`:<\/p>\n “`toml **Format:** `CODE:item1,count1;item2,count2|maxUses|expiryEpoch`<\/p>\n Changes take effect on server restart.<\/p>\n —<\/p>\n ## How It Works<\/p>\n 1. Player opens the GUI: `\/promo` **Statistics shown in the GUI:** —<\/p>\n ## Anti-Abuse Protection<\/p>\n Each player can redeem each code **exactly once**. This protection persists across: \u26a0\ufe0f **Note:** On offline-mode servers, users could theoretically use modified clients to bypass this. Server administrators should monitor usage and delete problematic codes if needed.<\/p>\n —<\/p>\n ## Data Storage<\/p>\n Redemption data is automatically saved to: **Contents:** **Do not edit manually** unless backing up. The mod manages this file automatically.<\/p>\n —<\/p>\n ## Real-World Examples<\/p>\n ### Example 1: Welcome Bonus ### Example 2: Anniversary Event (100 uses, expires 1 January 2026) ### Example 3: Complex Reward (3 items, 50 uses, never expires) ### Example 4: Seasonal Giveaway (expires 31 December 2025) —<\/p>\n ## Troubleshooting<\/p>\n **Issue:** “Invalid item” error when creating a code **Issue:** “Code already exists” when creating **Issue:** Player can’t redeem, but code looks valid **Issue:** Items aren’t appearing in inventory **Issue:** Server crashed after changing config —<\/p>\n ## Compatibility<\/p>\n – **Minecraft Version:** 1.16.5 —<\/p>\n ## Known Limitations<\/p>\n – Maximum 3 items per code via simple command (use `createraw` for more) —<\/p>\n ## Licence<\/p>\n Redistribution without credit is not permitted.<\/p>\n —<\/p>\n","protected":false},"excerpt":{"rendered":" Create and manage promotional codes to reward players with items. Perfect for events, giveaways, and starter bonuses. Includes anti-abuse protection and real-time statistics.<\/p>\n","protected":false},"featured_media":30292,"template":"","meta":{"_minecraft_slug":"betterrewards","_minecraft_project_id":"FBR8weIr","_minecraft_author":"M4riosDev","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":7,"_minecraft_follows":0,"_minecraft_client_side":"required","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"betterrewards.zip","_minecraft_size_bytes":548658,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-16T14:45:29.514442Z","_minecraft_date_created":"2026-04-30T01:07:21.314069Z","_minecraft_date_modified":"2026-04-07T12:02:44.379583Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/betterrewards","_minecraft_icon_attachment_id":30292,"_minecraft_imported_at":"2026-06-01T12:51:45+00:00","_minecraft_import_hash":"b239e86506f1babd7daa7e8259004bbb","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[844,104,91,92],"mod_loader":[106],"minecraft_version":[48],"class_list":["post-30291","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-economy","mod_category-forge","mod_category-storage","mod_category-utility","mod_loader-forge","minecraft_version-1-16-5"],"yoast_head":"\n
\n“`
\n\/promo create
\n\/promo create
\n\/promo createraw
\n“`<\/p>\n
\n“`
\n\/promo delete
\n“`<\/p>\n
\n“`
\n\/promo help
\n“`<\/p>\n
\n|———–|——-|——-|
\n| `CODE` | Letters, numbers, underscores, hyphens | `WELCOME`, `SUMMER2024`, `EVENT_01` |
\n| `item` | Minecraft item ID | Format: `namespace:name` (e.g., `minecraft:diamond`) |
\n| `count` | 1\u201364 | Quantity per item in the reward |
\n| `maxUses` | 0\u2013999 | `0` = unlimited redemptions |
\n| `expiryEpoch` | Unix timestamp (seconds) | `0` = never expires; see below for examples |<\/p>\n
\n|——|——-|
\n| 1 January 2025 | `1735689600` |
\n| 1 July 2025 | `1751500800` |
\n| 31 December 2025 | `1767225600` |<\/p>\n
\nminecraft:diamond minecraft:emerald
\nminecraft:golden_apple minecraft:enchanted_golden_apple
\nminecraft:netherite_sword minecraft:diamond_pickaxe
\nminecraft:diamond_axe minecraft:iron_sword
\nminecraft:respawn_anchor minecraft:bread
\nminecraft:coal minecraft:iron_ingot
\nminecraft:oak_log minecraft:obsidian
\nminecraft:amethyst_block minecraft:copper_ore
\n“`<\/p>\n
\n[[promocodes]]
\ncodes = [
\n “EARLY_EASTER:minecraft:diamond,5;minecraft:golden_apple,3|100|0”,
\n “FREESTART:minecraft:iron_sword,1;minecraft:bread,10|200|0”,
\n “DIAMONDS4ALL:minecraft:diamond,64|10|0”
\n]
\n“`<\/p>\n
\n2. Types the code name: `WELCOME`
\n3. Clicks “CONFIRM” (or presses Enter key)
\n4. If valid: items appear in inventory
\n – Overflow drops at feet if inventory full
\n5. If invalid: error message displayed
\n – Already used, expired, max uses reached, invalid code<\/p>\n
\n– **Redeemed:** `25\/100` (25 of 100 available items claimed)
\n– **Players:** `10` (10 unique players have redeemed something)<\/p>\n
\n– Name changes
\n– Multiple accounts on the same computer
\n– Server restarts
\n– Reinstalling the game<\/p>\n
\n“`
\nworld_folder\/promocodes_data.json
\n“`<\/p>\n
\n– Which codes each player has redeemed
\n– Total redemptions per code
\n– Custom codes created via commands<\/p>\n
\n“`
\n\/promo create WELCOME minecraft:diamond,5 minecraft:iron_sword,1 minecraft:bread,20 0 0
\n“`
\n– Unlimited uses
\n– Never expires
\n– Rewards: 5 diamonds, iron sword, 20 bread<\/p>\n
\n“`
\n\/promo create ANNIVERSARY minecraft:golden_apple,3 100 1735689600
\n“`<\/p>\n
\n“`
\n\/promo createraw STARTER:minecraft:diamond,10;minecraft:emerald,5;minecraft:enchanted_golden_apple,2|50|0
\n“`<\/p>\n
\n“`
\n\/promo create XMAS minecraft:red_concrete,20 minecraft:green_concrete,20 minecraft:gold_block,5 0 1767225600
\n“`<\/p>\n
\n– **Solution:** Check the item ID spelling (e.g. `minecraft:acacia_log` not `acacia log`)<\/p>\n
\n– **Solution:** Delete the old code first: `\/promo delete OLDCODE`<\/p>\n
\n– **Solution:** Check if:
\n – Player already redeemed it (1 per player)
\n – Code has expired (check expiryEpoch)
\n – Max uses reached (check redemption count in \/promo GUI stats)<\/p>\n
\n– **Solution:** Check inventory space. Overflow items drop at feet.<\/p>\n
\n– **Solution:** Check `promocodemod-server.toml` for syntax errors. Item IDs must be valid.<\/p>\n
\n– **Modloader:** Forge
\n– **Client\/Server:** Can be server and client (recommended)
\n– **Offline Mode:**
\n– **Online Mode:** <\/p>\n
\n– Item count limited to 1\u201364 per item
\n– No GUI for admins to create codes (use commands or config file)
\n– Codes are case-insensitive but stored in uppercase<\/p>\n