ForgeStore Owner Bot

What the bot does

The ForgeStore Owner Bot connects your ForgeStore store to your game server's Discord community. Once set up in under 5 minutes, it works silently in the background — alerting you to every sale, posting daily performance summaries, and automatically giving players their Discord roles when they purchase.

Installation

Step 1 — Create the Discord Application

1. Go to discord.com/developers/applications
2. Click New Application → name it ForgeStore
3. Under General Information, copy the Application ID — you'll need it later
4. Go to Bot → click Add Bot
5. Click Reset Token and copy it immediately — it's only shown once
6. Scroll down and enable these Privileged Gateway Intents:
   • ✅ Server Members Intent (required for auto-roles)
   • ✅ Message Content Intent

Step 2 — Invite the bot to your server

1. Go to OAuth2 → URL Generator
2. Under Scopes: check bot and applications.commands
3. Under Bot Permissions, check these:

   Permission	Why it's needed
   Send Messages	Post sale alerts and summaries
   Embed Links	Show rich embed cards
   Read Message History	Avoid duplicate messages
   Manage Roles	Assign Discord roles after purchases
   View Channels	Access the alert channel

4. Copy the generated URL → open it → select your server → Authorize

Step 3 — Configure the .env file

DISCORD_TOKEN=your_bot_token_here
DISCORD_CLIENT_ID=your_application_id
FORGESTORE_URL=https://forgestore.net
POLL_INTERVAL=30000      # poll for new sales every 30 seconds
EMBED_COLOR=7c3aed      # hex color for embeds (no #)

Step 4 — Install, deploy commands, and start

npm install
node src/deploy-commands.js   # register slash commands (run once)
npm start

If successful you'll see:

🚀 ForgeStore Owner Bot ready!
   Logged in as: ForgeStore#1234
   Serving 1 servers
⏰ Schedulers started — daily @ 09:00, weekly @ Mon 09:05
🔄 Starting sales polling every 30s

Keep it running (production)

npm install -g pm2
pm2 start src/index.js --name forgestore-bot
pm2 save        # save process list
pm2 startup     # auto-start on server reboot

Link Your Store

Before using any other command, link your ForgeStore store to the Discord server.

Get your API key

1. Log in to your ForgeStore dashboard
2. Go to Store Settings → API
3. Copy your API Key and Store ID

Link the store

/link api_key:fs_live_abc123 store_id:1

The bot will test the connection and confirm with your store name and current stats.

Configure your timezone (important)

Set your timezone so daily summaries post at 09:00 your local time, not UTC:

/config timezone tz:Europe/Paris
/config timezone tz:America/New_York
/config timezone tz:Asia/Tokyo

Set the alert channel

/config alerts channel:#sales-alerts

All sale alerts, daily summaries, goal alerts, stock warnings, and milestone celebrations go to this channel.

All Commands

Type /help in Discord to see the full list anytime.

🔗 Setup

📊 Statistics

🛒 Orders & Players

🏪 Store Management

🎟️ Coupons & Discounts

🎯 Community Goals

🎭 Auto-Roles

🛡️ Moderation

🔔 Alert Preferences

🎭 Automatic Discord Roles

The bot's most powerful feature. When a player purchases a package, they automatically receive a Discord role — no admin action required.

How it works

Setup (Minecraft example with 4 ranks)

# Map each rank package to a Discord role
/roles add "VIP" @VIP
/roles add "VIP+" @VIP-Plus
/roles add "MVP" @MVP
/roles add "Elite" @Elite

# Verify your mappings
/roles list

/verify Notch

Now when Notch purchases VIP Rank on the store, the bot automatically gives them @VIP in Discord within 30 seconds — and posts a confirmation message.

Confirmation message

When a role is successfully assigned, the bot posts in the alert channel:

If a player forgets to /verify

Their purchase still goes through and they receive their in-game rank normally via the plugin. They just won't get the Discord role until they run /verify. The role won't be retroactively assigned for past purchases.

🔔 Alerts & Automatic Posts

Once an alert channel is configured, the bot posts automatically without any manual trigger. Each alert type can be individually toggled with /alert config.

Sale alert

Fires within 30 seconds of every completed purchase. The embed color changes based on the amount:

Automatic scheduled posts

🏆 Milestone Celebrations

The bot automatically celebrates your store's growth. Each milestone fires once and is permanently remembered — it will never fire again for that milestone.

Order milestones

Revenue milestones

New player alert

When a player makes their very first purchase on your store, the bot posts:

Toggle milestone alerts with /alert config milestones:false.

🔀 Multi-Store Support

If you manage multiple stores, you can switch between them without re-running /link.

/switch list              # see all your stores — active one marked with ▶️
/switch to store_id:2    # switch to store 2

Each Discord server can manage a different store. If you run multiple Discord communities, install the bot in each and link a different store in each server.

🎁 Personal Discounts

Create a personalized coupon for a specific player — useful for compensating issues or rewarding loyal supporters.

# 20% off, 1 use, expires in 48 hours
/discount player:Notch percent:20 uses:1 expires_hours:48

# 50% off, usable 3 times, 7-day validity
/discount player:ProPlayer percent:50 uses:3 expires_hours:168

The bot generates a unique code like NOTCH_20OFF_X7K2. Share it directly with the player. The code is only usable the number of times specified.

⚙️ Configuring Alerts

Toggle individual alert types so your channel only shows what's relevant to you.

/alert config sales:true daily:true weekly:false goals:true stock:false milestones:true

🛠️ Troubleshooting

Commands don't appear in Discord

• Make sure you ran node src/deploy-commands.js after setup
• Global slash commands can take up to 1 hour to propagate — this is a Discord limitation, not a bot issue
• Check that the bot has Use Application Commands permission in the server

No sale alerts are posting

• Run /config status — verify the alert channel is set
• Check the bot has Send Messages and Embed Links permissions in the alert channel
• Run /alert status — confirm sales is ON
• Verify your ForgeStore API key in /config status — re-run /link if it's changed

Auto-roles aren't being assigned

• The player must have run /verify TheirUsername first
• The bot's role must be above the target roles in Server Settings → Roles
• The bot needs Manage Roles permission
• The package name must contain the keyword (not exact match) — check with /roles list
• Run /status to confirm the bot is connected and polling

Daily/weekly summaries are posting at the wrong time

• Set your timezone: /config timezone tz:Europe/Paris
• The default timezone is UTC — if you haven't set a timezone, summaries post at 09:00 UTC
• Run /config status to see the current timezone setting

/link fails with an error

• Double-check your API key — copy it fresh from Store Settings → API
• Make sure FORGESTORE_URL in .env points to your ForgeStore instance with no trailing slash
• The API returns 401 if the key is wrong — 404 if the store ID doesn't exist

Bot crashes on startup

• Check .env is present and DISCORD_TOKEN is set correctly
• Run npm install to ensure all dependencies are installed
• Node.js v18 or higher is required — check with node --version
• If using PM2, run pm2 logs forgestore-bot to see the full error output