The shop, items and trading

A currency with nothing to buy is a scoreboard. The shop is what turns a balance into a decision, so it is worth building before you switch FlaviBot's earning rules on.

The shop lives on the Economy page, Shop tab: categories, items and sales.

Categories

Categories group items into browsable sections. Each has a name, an optional description, an emoji and a position. They are optional: items without one still show up in the shop.

Items

Every item has a name, a price, and optionally a description, an emoji, an image and a category. In Discord, the item's card shows the image, or, without one, the picture of a custom emoji. Beyond that:

Deleting an item also destroys every copy of it in members' inventories, plus any market listing for it. To pull an item from the shop while letting owners keep what they bought, switch Enabled off instead of deleting.

What an item actually does

Each item is one of four kinds.

Role grants a role. Leave the duration empty for a permanent role, or set one for a temporary role that is removed automatically when the timer runs out, even if the bot restarts in between. The duration can run from one minute to a year.

XP boost multiplies the buyer's XP for a while. The multiplier goes from 1.25x to 3x in steps of 0.25, and the duration from five minutes to thirty days. It stacks with any role XP multiplier the member has, and the combined result is capped at 3x, so a boost can never push someone past what the server could already configure. Only the strongest active boost counts. A boost used while one at least as strong is running is not wasted: it starts when that one ends, then runs its full duration. A stronger boost takes over straight away. An XP boost won as a quest reward works the same way.

Workflow runs a list of actions, up to ten of them, through the same automation pipeline as the autoresponder. You choose when they run:

• Purchase: on buying the item.
• Use: every time the member runs /economy item use.
• On consumption: only when a copy is actually burned, which means the item has to be both Usable and Consumable, otherwise it never fires.

An item can carry up to three such lists, one per moment (Purchase, Use, On consumption), each running its own actions. A use that burns a copy of an item with a Use list and an On consumption list runs both.

Cosmetic does nothing on purpose: a collectible, a badge, something to show off in an inventory or to require as the price of entry for something else.

Items used on another member

A workflow item can be used on another member: a tomato that costs its target 100 coins, a gift that hands them an item, a cake that posts a message about them. Switch Used on another member on in the item's editor. Members then pick a target when they use it, with /economy item use item:Tomato target:@Bob or the member picker on the item's card in their inventory.

Its Use and On consumption workflows can read who it was used on, next to {user.*}, the member who used it:

An action aims at the target through its usual member field. The Aim at the target button on a step fills it in for you:

{ "amount": 100, "target": { "type": "specific", "user_id": "{target.id}" } }

Without it, the step acts on the member who used the item.

Only some actions can run in such an item, because anyone can buy it: adding or removing coins, giving or taking an item, posting a message, waiting or stopping, and the variable and data actions, which act on nobody. Moderation, roles, nicknames, voice, DMs and every other action are refused when you save. The Purchase workflow is not aimed at anyone and keeps every action.

Every use is checked before anything happens, and refused with the reason:

• not on yourself, unless Can be used on yourself is on;
• not on a bot, and only on a member of the server;
• the server's minimum account age, on both sides;
• members who joined in the last 24 hours (Protection for new members) can neither use it on others nor be targeted;
• members holding a protected role can't be targeted, and the roles that can't be robbed are protected too unless you turn that off;
• members who blocked items aimed at them can't be targeted (Members can block it, on by default);
• a cooldown per member using it (1 minute by default) and per target (1 hour by default);
• a daily cap per target (5 by default, counted per UTC day, empty for no cap); only uses that happened count;
• the bot must be able to post in the channel, because every use is public.

A use that passes posts a new message in the channel, such as @Alice used Tomato on @Bob., which pings nobody. Its Block items aimed at me button lets whoever reads it opt out on this server, and Allow items again undoes it. Members also find the switch in /economy menu, under Help, in Items used on you. A block is not part of the economy: an economy reset leaves it.

With The target must accept on, the bot posts a request that pings the target, with Accept, Decline, Block items aimed at me and Cancel. Nothing is used until they accept, and nothing happens if they decline, don't answer within 5 minutes, or the request is cancelled. The cooldowns are spent when the request is sent, and a member can ask the same target again only after the 5 minutes, whatever the answer.

The item is used even when its workflow then fails, for example when the target cannot pay what a step takes from them, exactly as any other item's workflow. Only a workflow that could not be started at all gives the item back.

Purchase requirements

An item can demand any combination of:

• a required role;
• a minimum balance, checked against what the member is holding before paying, on top of the price, so you can reserve an item for members who have already accumulated a certain amount;
• up to five required items, all of which must be owned, so items can chain into a progression;
• a minimum level, read from the level system.

All of the requirements you set must be met. A member who fails any of them is told the requirements are not met rather than being charged. The required items are checked at the moment of the purchase, so a prerequisite bought a second earlier counts. An item cannot require itself, and two items cannot require each other.

Upgrades. Switch on Use up the required items on purchase and buying the item takes one copy of each required item for every copy bought: Chest II can cost a Chest I plus coins. The purchase reply says what it used up. If the purchase is refunded (a role grant failed, for instance), the used-up items come back with the coins.

Sales

A sale is a time-boxed discount over the whole shop, one category, or one item, from 1% to 99%, with a start (optional, immediate if left empty) and an end (required).

Sales never stack. If several apply to the same item, the largest discount wins and that is the price charged.

Buying and using

The item options autocomplete, so members can type a name instead of hunting for an id.

The panels are also one click away from /economy menu. An item's card shows its price (struck through during a sale), the stock left, how many you own, what it requires, and, under Details, what it does. Buy several asks how many, up to what you can buy right now. A double click buys once. A refused purchase says why on the card. A panel closes after 10 idle minutes.

A purchase is one atomic operation: the availability window, the stock, the per-member limit and the balance are all re-checked at the moment of payment, and either everything happens or nothing does. If the item's effect then fails in a way that leaves the member paying for nothing, such as a role the bot cannot grant or an XP boost that could not be activated, the item is taken back and the coins are refunded.

Sell-back deserves one note. The refund is the sell-back percentage of the lower of the item's current price and the average price the member actually paid for it. That prevents buying at a discount during a sale and selling back at full price for a profit. The inventory card shows what one copy sells back for right now.

Sending coins to another member

/economy pay user amount transfers coins. The bot asks for a confirmation before anything moves.

Under Transfers on the Settings tab:

• Allow transfers can turn the whole thing off.
• Transfer tax (%) is burned on every transfer: the sender pays the full amount, the recipient receives the amount minus the tax, and the difference leaves circulation. It is your main lever against a currency that only ever grows.
• Daily transfer cap limits how much one member can send per UTC day. Empty means no cap.

You cannot pay yourself or a bot, and both sides must clear the minimum account age gate. A transfer that would push the recipient past the maximum balance is refused rather than partially delivered.

Trading

/economy trade offer user opens a trade panel in the channel. Both members stage what they are putting in, coins and items, and both must lock before anything moves. Execution is a single operation that re-checks both sides' balances and inventories, so nothing can be traded twice or traded away in the meantime.

A trade expires after 10 minutes, and /economy trade cancel drops your pending one. Items marked as not tradeable cannot be staged.

The marketplace

The market is member-to-member selling, without both people needing to be online at once.

A public /economy market view turns its pages only for the member who ran it. Anyone else who presses a page button gets their own private copy of that page, and its Browse and buy button opens anyone's own panel.

Listing costs a fee, taken when the listing is created: a percentage of the total asking price, 2% by default, never less than one coin. It is not refunded if you cancel, which is what stops the market being spammed with listings nobody intends to sell.

The items are held in escrow while the listing is up, so they cannot be traded or used at the same time. Listings run for 7 days, and the items come back if one expires or is cancelled. Only tradeable items can be listed.

Reacting to a purchase

economy_item_purchase is an autoresponder trigger: it fires after a purchase commits, and can be limited to specific items. Use it to announce a purchase, open a ticket, or give something the item itself cannot.

Autoresponder actions can also give and take items directly, so an automation can hand out a collectible without a shop transaction. See triggers and actions.