Game Server Plugin API

The ForgeStore Plugin API lets your game server plugin automatically deliver purchases to players. When a player buys a package, ForgeStore stores the server command in a queue. Your plugin polls the queue, executes the commands, and marks them as done.

How it works

1
Player buys a package
The player selects a package on the store, pays via ForgeStore Pay, and the payment is confirmed.
3
Command added to queue
ForgeStore receives the webhook from ForgeStore Pay, confirms the payment, and adds the server command to the queue with the player's username.
3
Plugin polls the queue
Every 30 seconds, your plugin calls GET /api/plugin/queue to check if any commands are pending.
4
Execute the commands
For each pending command, the plugin executes it on the server (e.g. lp user {player} parent set vip).
7
Mark as done
After execution, the plugin calls DELETE /api/plugin/queue with the command IDs. They are removed from the queue.
🔑 Authentication
Every request must include your server secret key as a header:
X-ForgeStore-Secret: YOUR_SERVER_SECRET_KEY

Your secret key is found in: Dashboard → Store Settings → Developers → Server Secret Key
All requests must use HTTPS. Rate limit: 60 requests / minute.

Command Variables

When you define a server command on a package, you can use these variables. ForgeStore replaces them automatically:

Variable Description Example
{player} The player's username as entered at checkout Notch
{name} Alias for {player} Notch
{id} Same as {player} (UUID on supported games) Notch
{uuid} Same as {player} Notch
{amount} The purchase amount (formatted, 2 decimals) 9.99
Example command for Minecraft + LuckPerms:
lp user {player} parent set vip

API Endpoints

GET /information Get Store Information

Returns general information about the store associated with your secret key. Use on plugin startup to verify the connection.

Response
{
  "account": {
    "id": 1,
    "name": "Nexus Gaming",
    "currency": {"iso_4217": "EUR", "symbol": "€"},
    "game_type": "Minecraft: Java Edition"
  },
  "server": {
    "id": 1,
    "name": "Nexus Gaming"
  }
}
GET /queue Get Command Queue

Returns players who have online commands pending, and whether offline commands are waiting. Call this every 30 seconds. If execute_offline is true, call /queue/offline immediately.

Response
{
  "meta": {
    "execute_offline": true,
    "next_check": 30,
    "more": false
  },
  "players": [
    {"id": 1, "name": "Notch", "uuid": "Notch"}
  ]
}
GET /queue/offline Get Offline Commands

Returns commands that do not require the player to be online. Execute these immediately when you receive them. After execution, call DELETE /api/plugin/queue with the command IDs.

Response
{
  "meta": {"limited": false},
  "commands": [
    {
      "id": 1,
      "command": "give Notch diamond 64",
      "payment": 42,
      "conditions": {"delay": 0},
      "player": {"name": "Notch", "uuid": "Notch"}
    }
  ]
}
GET /queue/online/{playerName} Get Online Commands for a Player

Returns pending commands for a specific player who is currently online. Only call this when the player is confirmed online on your server. After execution, call DELETE /api/plugin/queue.

Parameters
playerName string The username of the online player
Response
{
  "commands": [
    {
      "id": 5,
      "command": "lp user Notch parent set vip",
      "payment": 42,
      "conditions": {"delay": 0, "slots": 0}
    }
  ]
}
DELETE /queue Mark Commands as Executed

Call this after successfully executing commands on your server. Pass the IDs of the commands that were executed. They will be removed from the queue and will not be returned again.

Request Body (JSON)
ids array Array of command IDs: [1, 2, 3]
Response
204 No Content
GET /bans List Bans

Returns all bans for this store. You can use this to prevent banned players from receiving purchases.

Response
{
  "data": [
    {
      "id": 1,
      "time": "2025-01-15T10:00:00",
      "reason": "Chargeback fraud",
      "user": {"ign": "Griefer123", "uuid": "Griefer123"}
    }
  ]
}
POST /bans Create a Ban

Ban a player from purchasing on this store. Useful if you detect fraud or cheating directly from the game server.

Request Body (JSON)
username string The username of the player to ban
reason string Reason for the ban (shown in admin panel)
Response
201 Created — {"success": true}
GET /payments List Recent Payments

Returns up to 100 recent successful orders. Useful for audit logs or in-game notifications.

Parameters
limit integer Number of results (max 100, default 25)
Response
[
  {
    "id": 42,
    "amount": "9.99",
    "date": "2025-01-15T10:00:00",
    "currency": {"iso_4217": "EUR", "symbol": "€"},
    "status": "Complete",
    "player": {"name": "Notch"},
    "packages": [{"id": 1, "name": "VIP Rank"}]
  }
]
GET /user/{player} Player Lookup

Returns detailed information about a player — their full purchase history, total spent, and ban count.

Parameters
player string Username of the player to look up
Response
{
  "player": {"id": "Notch", "username": "Notch"},
  "banCount": 0,
  "chargebackRate": 0,
  "payments": [
    {"txn_id": "FS-42", "time": 1736942400, "price": 9.99, "currency": "EUR", "status": 1}
  ],
  "purchaseTotals": {"EUR": "29.97"}
}
GET /player/{id}/packages Player Active Packages

Returns all packages the player has purchased. Filter to a specific package to check if they own it. Useful for permission checks in-game.

Parameters
id string Username of the player
package integer (Optional) Filter to a specific package ID
Response
[
  {
    "txn_id": "FS-42",
    "date": "2025-01-15T10:00:00",
    "quantity": 1,
    "package": {"id": 1, "name": "VIP Rank"}
  }
]

📋 Polling Loop (pseudocode)

Here is the typical flow your plugin should implement:

every 30 seconds:
  queue = GET /api/plugin/queue

  // 1. Execute offline commands
  if queue.meta.execute_offline:
    offline = GET /api/plugin/queue/offline
    for each command in offline.commands:
      execute(command.command)
      mark_done.append(command.id)

  // 2. Execute online commands for each player
  for each player in queue.players:
    if isOnline(player.uuid):
      cmds = GET /api/plugin/queue/online/{player.name}
      for each cmd in cmds.commands:
        if player.inventorySlots >= cmd.conditions.slots:
          execute(cmd.command)
          mark_done.append(cmd.id)

  // 3. Mark all executed commands as done
  if mark_done is not empty:
    DELETE /api/plugin/queue  body: {"ids": mark_done}

⛏️ Minecraft

Compatible with Paper, Spigot, and Bukkit. Requires Java 11+.

Installation

1
Download the plugin
Download ForgeStore.jar from your Dashboard → Plugins. Drop it in your plugins/ folder.
2
Configure
Start the server once to generate plugins/ForgeStore/config.yml. Set api_key and store_id.
3
Reload
Run /fs reload or restart the server. Check the console for [ForgeStore] Connected ✓.

Example commands

# LuckPerms — add rank
lp user {player} parent set vip

# Give items
give {player} diamond 64

# Run custom command
eco give {player} 1000

# Broadcast purchase
broadcast &6{player} &fjust bought &6VIP&f on our store!
💡
Use LuckPerms for permissions. It's the most reliable way to manage ranks across restarts.

🏚️ Rust

Compatible with uMod (Oxide) and Carbon. Requires Rust server 2023+.

Installation

1
Download the plugin
Download ForgeStore.cs from your Dashboard → Plugins. Drop it in oxide/plugins/ or carbon/plugins/.
2
Configure
The config file is generated at oxide/config/ForgeStore.json. Set ApiKey and StoreId.
3
Reload
Run oxide.reload ForgeStore in the server console.

Example commands

# Give kit
inventory.giveto {player} kit_vip

# Add VIP group (Oxide)
oxide.usergroup add {player} vip

# Give item by item ID
giveplayeritem {player} 1751045826 1

# Custom server points
sr add {player} 500

🚗 FiveM

Compatible with ESX, QBCore, and standalone FiveM servers.

Installation

1
Download the resource
Download the forgestore resource folder from Dashboard → Plugins. Place it in your resources/ folder.
2
Add to server.cfg
Add ensure forgestore to your server.cfg. Set the API key and store ID in forgestore/config.lua.
3
Restart
Restart the server or run refresh then start forgestore in the console.

Example commands (server console)

# ESX — add money
ExecuteCommand("esx:addMoney {player_license} 5000")

# QBCore — add item
ExecuteCommand("qb-inventory:addItem {player} water 5")

# Give VIP job (ESX)
ExecuteCommand("esx:setJob {player_license} vip 0")

# Custom event trigger
TriggerEvent("forgestore:giveVip", "{player}")
⚠️
FiveM uses player licenses (Steam/FiveM identifier), not player names. Make sure your players enter their in-game name at checkout, and map it to their license in your server's player database.

🔧 Garry's Mod

Compatible with all Garry's Mod server types. Uses GLua.

Installation

1
Download the addon
Download forgestore.lua from Dashboard → Plugins. Place in garrysmod/addons/forgestore/lua/autorun/server/.
2
Configure
Edit the top of the file: set FORGESTORE_API_KEY and FORGESTORE_STORE_ID.

Example commands

# ULX — add to group
ulx adduserid {steam_id} vip

# SAM — set rank
sam addrank {player} vip

# Give DarkRP money
drp setmoney {player} 5000

# Custom Lua event
forgestore.trigger("{player}", "vip_purchased")

📝 Command Variables

These variables are replaced with real values when a command is executed:

VariableReplaced withExample
{player}Player's username at checkoutSteve
{player_lower}Username in lowercasesteve
{player_id}Player's internal ID76561198...
{order_id}ForgeStore order ID12345
{package}Package nameVIP Gold
{amount}Amount paid (formatted)€9.99
{store}Store nameMy Server Store
{date}Purchase date (YYYY-MM-DD)2025-01-15
© 2026 ForgeStore · [email protected]