The Kit Manager: kits players claim with /kits

What a kit is

A kit is a named bundle of items you assemble once, and a player takes the whole bundle with one Discord command. A free starter kit everyone gets on their first day, a weekly care package, a paid raid loadout — all of them are the same object with different settings.

A kit is not a shop item. The shop sells one row at a time; a kit hands over between 5 and 10 items together, for one price, with its own rule about how often each player may take it. An item can sit in a kit without being on sale in the shop at all, which is exactly what a starter kit is.

Everything else is shared with the rest of the economy. A kit is paid for out of the same wallet, recorded in the same transaction history, and delivered by the same machinery as a purchase — so a claim appears in /my-transactions and on the Transactions tab beside everything else, and a refund works the same way. There is no second currency and no second ledger.

You build kits on your server's Economy page, on the Kit Manager tab. Players claim them in Discord with /kits.

Before you start

Three things have to be true, and none of them is specific to kits:

• Your economy is set up. Currency named, economy enabled. See Setting Up Your Server Economy.
• Your item catalog has been scanned. The kit editor searches the same catalog the shop searches, and it cannot offer items nobody has scanned. The Scan Game Items button on the Shop tab is what fills it. See The Item Catalog and Shop.
• Your game can be delivered to. Building a kit is refused on a game whose economy cannot hand items over, at the moment you try, with a message saying so. That refusal is deliberate: a kit that could be claimed but not delivered would take a player's coins for nothing. Per-game economy support lists which games can deliver.

Players also need to have run /link before they can claim anything — a kit is delivered to a character, and the platform has to know which one. See Linking Discord Accounts to In-Game Players.

Building a kit

Open Economy → Kit Manager and press + New kit. The form is in three parts.

The kit itself. A name of 1 to 80 characters (Starter Kit), an optional description of up to 500 characters, and a price.

Price. A whole number of zero or more, in your own currency. Zero makes the kit free, which is what you want for a starter kit — it is an ordinary price of nothing rather than a separate switch, so the price and the "is it free" answer can never disagree. A free kit skips the balance check entirely, so "not enough coins" can never be the reason a free kit is refused.

How often can each player take it? Two independent caps. The next two sections cover them.

What is in it. Search your scanned catalog and add items. Each line carries a quantity of 1 to 1000. An item may appear only once in a kit — to hand over five bandages, set that line's quantity to 5 rather than adding the item five times.

While you are filling the form in, the Save button says why it is disabled instead of refusing after you press it.

The size limits, and why they exist

The 5-to-10 rule is a floor as well as a ceiling: a kit holding four items is refused. A kit is meant to be a bundle worth one command, and a two-item "kit" is two shop items.

The 20-kit cap is counted per server — or, where your servers share one economy, per game inside the group. Two games in a linked group get 20 kits each, and each may have its own kit called starter without clashing. See Sharing One Economy Across Servers.

When you reach 20 the panel says so and names the remedy: delete a kit you no longer use, or switch one off. Switching off does not free a slot — an inactive kit still occupies one. That is on purpose, because switching a kit off is reversible and deleting it is not.

Claim limits: two caps, and you can use either, both or neither

This is the part worth reading twice, because the two caps look alike and do different jobs.

Limit the total each player can ever take. A counter that never resets. Once a player has used their allowance it is gone for good. Set it to 1 and you have a one-time kit — the free starter kit everyone gets once.

Limit how often, with a reset. A fresh allowance every day or every week. A player who has used this window's allowance gets it back when the window rolls over.

They are separate fields, so all four combinations are expressible:

Whatever you set, the panel shows the sentence your players will see underneath it, live, as you type. Check that sentence against what you meant — two checkboxes and two numbers are easy to fill in and easy to misread, and the sentence is word for word what the bot prints.

The total cap is checked first. A player whose permanent allowance is spent is told it will never come back, rather than being told to try again tomorrow about a kit they can never claim again.

When the day and the week roll over

The resetting cap counts claims inside a calendar window measured in UTC. It is not a cooldown timer.

• Per day means the window from 00:00 UTC to 00:00 UTC the next day.
• Per week means the window starting at 00:00 UTC on Monday and running to 00:00 UTC the following Monday. Weeks start on Monday, not Sunday.

The difference from a cooldown matters. A cooldown of "once every 24 hours" locks a player who claimed at 23:00 out until 23:00 tomorrow. A daily window does not: that player claims again an hour later, when the day rolls over, and then not again until the day after.

UTC is deliberate, and it is the same instant for everybody. Your players are in different time zones and so are the machines; a reset pinned to "midnight wherever the server thinks it is" would move when the server did. If your community sits in one time zone and the 00:00 UTC reset falls awkwardly for them, say so in the kit's description — the reset hour is not configurable.

The bot never makes a player work this out. When a kit is not available it says how long until it comes back, as a duration: "It is available again in 3h 12m."

Claiming a kit in Discord

Three subcommands, all answering privately so that one player's remaining allowance is not posted to the channel:

Pick the server first on /kits show and /kits claim. The kit box suggests kit names, and it cannot know whose kits to offer until the server has been chosen.

A kit a player cannot claim right now is still listed, marked with a lock, with the reason attached. Hiding it would leave players asking for a kit they can plainly see exists.

Running the command twice does not charge twice. A repeat of the same request is answered with Already Claimed and the note that nothing was charged again.

/kits is a player command rather than an administrative one, and it is gated on two named abilities, the same way the shop is. economy.kits.browse covers /kits list and /kits show; economy.kits.claim covers /kits claim — because looking at a kit and spending a wallet on one are two different decisions, exactly the split between economy.shop.browse and economy.buy. Both sit in the member preset, so a role you have given member already holds them.

If `/kits` refuses someone whose `/buy` works, grant the ability — that is now all it is. Run /permissions role role:@YourRole to see what the role holds, then /permissions grant role:@YourRole capability:economy.kits.browse (and economy.kits.claim) to add what is missing, or /permissions preset role:@YourRole preset:member to give the whole player-side set at once. The refusal names the ability it wanted and who can hand it out, so nobody has to guess. Every ability is listed in Setting up Discord roles.

Granting economy.kits.browse without economy.kits.claim is a real configuration and a useful one: the role can see every kit, its price and its limit, and cannot take one. That is the shape the shop already had, and kits now match it.

Why a refusal says which refusal it is

"You cannot claim this kit" is the same sentence for a player who is 20 coins short, one who used their one-time starter kit in March, and one who can have it again in three hours. Those have three different remedies, so the bot never gives the generic answer. There are four distinct refusals:

A player with no wallet gets a different message again: they are told to run /link first, because linking is what creates the wallet.

None of those refusals costs anything. The eligibility and balance checks happen before any money moves, so a refused claim never burns an allowance and never debits a wallet.

When delivery fails after the money has gone

This is the case worth understanding before a player writes to you about it.

A claim is committed first — the debit, the transaction record and the claim are written together — and then the items are handed to the game server, one line at a time. Delivery is a call to a machine that might be rebooting, so it happens outside that commit rather than holding your whole economy up while a socket times out. Which means a kit can be paid for and then fail to arrive, and there is a rule for every version of that.

Nothing arrived. The whole price goes back, through the same refund path an undelivered purchase uses, and the claim does not count against the player's limits. Their one-time starter kit is not spent on a hand-over that never happened. The bot answers with a red Kit Not Delivered card that says outright they have not been charged.

Some arrived, some did not. The price of the lines that failed is refunded pro rata, and the claim does count — the player is holding items. The split is by line, not by what each item is worth, because a kit carries one price and no per-line prices to divide up. Rounding goes to the player: a 7-item kit priced at 100 with 2 failed lines refunds 29, not 28. The bot answers with a yellow Kit Partly Delivered card listing exactly which items did not arrive, and why.

Everything arrived. Nothing to do. The bot confirms the items are on their way.

The player was not linked. Refunded in full, does not count against their limits, and the reply tells them to run /link and claim again.

A failed kit line is refunded, not retried. A single shop purchase that fails is re-driven automatically for a while. A kit is not, and the difference is deliberate: the whole claim is one transaction covering up to ten hand-overs, so re-driving it would deliver the lines that already succeeded a second time. Paying the player back and letting them claim again is the outcome that cannot double-deliver.

A refund is a real transaction. Point players at /my-transactions, or look at the Transactions tab yourself, to see it. Purchases, Delivery and Refunds explains what each delivery state means.

One exception: on a game with no automatic delivery at all the claim is recorded for an admin to hand over rather than refunded, and the player is told so. You should not meet this — building a kit on such a game is refused — but it can happen if a game lost its delivery method after the kit was built.

One wallet, one allowance, across linked servers

Where your servers share an economy a player has one wallet for the group, and their kit allowance is counted against that wallet.

So claiming a one-time starter kit on server A and then again on server B is not possible: it is the same player and the same allowance on both. That holds even for two claims fired a second apart.

Kits themselves are still per game. A group running two games has two separate kit lists, because an item id from one game means nothing to the other.

Editing, switching off and deleting

Editing. Change a kit's name, description, price, limits or contents at any time. Re-pricing does not require touching the item list. New limits apply to claims from that moment on; they do not retroactively undo claims already made.

Switching off. The Live column toggles a kit. An inactive kit disappears from /kits list, and anyone who tries to claim it is told it is switched off. Its claim history is kept, so switching it back on resumes exactly where everybody was.

Deleting. Deleting a kit deletes its claim history with it. That matters more than it sounds: delete a one-time starter kit and re-create it under the same name, and every player may claim it again, because the record of who already had it went with the old kit. If you only want to stop a kit being claimed, switch it off rather than delete it.

Deleting claws nothing back and refunds nothing. Kits already claimed stay claimed and the currency stays spent.

Common problems

"A kit holds between 5 and 10 items. This one has 4." Add items until there are at least five, or fold the idea into the shop instead.

"This server already has 20 kits." That is the cap. Delete one you no longer use; switching one off does not free the slot.

"There is already a kit called ... on this server." Kit names are unique per server, because the name is what a player types. Rename one of them.

The item I want is not in the search. The kit editor searches your scanned catalog. Run Scan Game Items on the Shop tab. If the item still does not appear, the scan did not find it on your server — see The Item Catalog and Shop.

"The economy cannot deliver items on this game yet." Your game has no automatic item delivery, so kits are refused rather than sold and left undelivered. Per-game economy support carries the current list.

A player says they were charged and got nothing. Check the Transactions tab. If the delivery failed they were refunded automatically, in full or pro rata, and the refund is a row of its own. If several players report the same kit, the item ids inside it are the first thing to check.

Players report a kit resetting at an odd hour. Daily and weekly windows roll over at 00:00 UTC, not local midnight, and weeks start on Monday. That is the answer, and it is not configurable.

For anything else, Economy, Linking and Chat Bridge Troubleshooting covers the symptoms the whole economy can produce.