Skip to main content

Shop system

This page describes how server admins maintain the shop catalog, orders, and subscriptions in daily operations.

For behavior from the player perspective and the overall concept, see:

Admin areas involved​

Navigation paths:

  • Server Admin -> Items (items and their categories on one page)
  • Server Admin -> Orders
  • Server Admin -> Transactions
  • Server Admin -> Subscriptions -> Available
  • Server Admin -> Subscriptions -> Active

Maintaining item categories​

Categories sit in the side menu of Server Admin -> Items, in the order players see them in the shop. On a phone the menu is a bar above the list that opens the category list.

  • Create a category with + Category below the menu; names stay unique per server.
  • Drag a category by the handle on its left to change the order, which also drives the grouping order in the shop.
  • The pencil on the right opens the category to rename it, restrict it to allowed groups, or delete it.
  • Deleting a category does not delete item sets; those item sets lose their category assignment and appear under Without category.
  • Restricted categories carry a lock icon in the menu. Hover it to see the allowed groups.
  • The search above the list finds items by name or class name across all categories.

Maintaining item sets​

  • Create and edit item sets with:
    • name, description, image URL,
    • price,
    • item list,
    • availability flag,
    • per-player max orders and period (lifetime/daily/weekly/monthly),
    • allowed groups,
    • assigned category.
  • Deleting an item set removes it from future purchases; historical orders stay visible in order history.
  • Item-set restrictions are marked with a shield icon in Server Admin -> Items. Hover the icon to see allowed groups.

Copying the shop from another server​

If your organization runs several servers, a new one can start with the shop of an existing one instead of an empty catalog. Open Server Admin -> Items -> Copy from another server (or pick From another server in the shop step of the setup wizard) and choose the server to copy from.

  • The copy is one to one: categories in their order, item sets with prices, item lists, availability, per-player order limits, descriptions and all translations, and the subscription offers.
  • Every image is copied into this server's own storage. Editing or deleting an item on the other server later never changes this shop, and the other way round.
  • Group restrictions belong to one server's groups. A restriction carries over when this server has a group of the same name (upper and lower case don't matter). For every group this server doesn't have, the copy asks first what to do: map it to one of this server's groups, copy its categories and items as not available in the shop, or leave them out. A category left out takes all its items with it; an item restricted to several missing groups is left out as soon as one of them is. Anything copied as not available is listed in the result with the missing group: create the group or change the restriction, then switch Available in shop back on.
  • If this shop already has items or categories, choose Add to it (everything stays; categories with the same name are merged) or Replace it (this shop's categories, items and copied subscription offers are deleted first). Replacing also removes those items from players' carts and favourites.
  • Orders, active subscriptions, coupons and shop settings are not copied.
  • Only servers of the same organization on which you may edit items are offered. You need itemsets.edit on both servers, plus itemsets.delete here to replace. Subscription offers come along when you hold subscriptions.view_available on the other server and subscriptions.create_available here (and subscriptions.delete_available to replace); otherwise the copy skips them and says so.
  • Every copy is recorded in the audit trail.

Order operations for admins​

  • Overview supports filtering by players, item names, item sets, and the order code.
  • Every order is shown by a four-character code such as #7KQM — to players in their order history, balance history and Discord, and to staff here. The code is random, so it reveals nothing about order volume; ask a player for it when they report a problem with an order. The global admin search finds orders by code as well.
  • Manual order creation supports:
    • target player (optional),
    • place-based or manual coordinates,
    • item sets and manual item lines.
  • Order details provide three key operations:
    • Cancel (undelivered only): marks order canceled.
    • Refund (delivered only): partial or full by quantity, with required reason and player balance credit.
    • Redeliver (delivered only): creates zero-cost follow-up order linked to original order.

Operational notes:

  • Redelivery is quantity-capped by prior redelivery history.
  • Refund tracking is quantity-based per order item to avoid over-refunding.

Transaction overview for admins​

  • The overview is read-only and meant for auditing money flow across the server.
  • Filters support player, description, date/time range, amount range, and category.
  • Use it to trace refunds, transfers, automated payouts, or admin balance adjustments before drilling into a specific player.
  • Direct balance changes still happen in Server Admin -> Players -> Player details -> Transactions.

Subscription operations for admins​

A subscription offer delivers one of two things:

  • Spawn — an item, vehicle or creature at a position the player picks, at every restart.
  • Membership — membership of an access group for as long as the subscription runs, optionally with a Discord role. What it unlocks is up to the group's rights: give it player.server.prioritized and you sell priority queue access; tie a coupon to the group and members get a shop discount.

Each offer has up to two prices, and you decide which:

  • In-game price — paid from the player's balance (or a faction's treasury for spawns), either at every paid restart or once a month. Leave it empty to sell for euros only.
  • Euro price per month — paid by card through your own Stripe account, see Monetization. Leave it empty to sell for in-game money only. Euro prices need payments set up for your organization.

Monthly subscriptions are charged in advance and renew on the same day each month until the player cancels; a cancellation takes effect at the end of the paid month. If a renewal cannot be paid, the subscription's benefits pause (the group is taken away, nothing spawns) and the player gets a Discord message; in-game renewals are retried daily, euro renewals by Stripe. After 7 days without payment the subscription ends. The price is fixed when a player books — changing an offer's price only affects new bookings.

Tier series group offers such as Bronze, Silver and Gold. A player holds at most one offer of a series. Moving up takes effect immediately and charges the difference for the rest of the month; moving down takes effect at the next renewal and can be taken back until then. Create series under Tier series on the offers tab, then pick the series and the tier in each offer.

  • Available subscriptions (offers): template definitions players can purchase.
    • Create, edit, activate/deactivate. An offer can only be deleted while none of its subscriptions run; deactivate it instead and running subscriptions continue.
  • Active subscriptions: concrete subscriptions of players and factions, filtered by running, ended or all.
    • Create/edit, reassign owner, and update location details of spawn subscriptions.
    • End a subscription now or at the end of the paid month, optionally refunding the last payment (in-game or through Stripe). Ended subscriptions stay listed as history.
    • Filtering by search, owner, faction, or map radius helps with operations at scale.

A permanent ban ends the player's subscriptions on that server at the end of the paid month (restart-billed ones right away); nothing is refunded. If the ban is lifted before then, the subscription continues. Temporary bans change nothing.

Every step of a subscription — started, renewed, payment failed, ended — fires the event player_subscription_changed, so Actions can welcome new members or tell your team.

When a subscription cannot spawn​

If the game server fails to place a subscription at a restart, dzbot settles it with the buyer directly rather than putting it in front of you: the charge for that restart is refunded automatically to whichever wallet paid it, and the player sees a Spawn problem badge with the reason on their subscription. It is idempotent, so a repeated import of the same restart does not refund twice.

For that reason these failures deliberately do not appear in Server diagnostics — the fix belongs to the player's chosen spot, not to your configuration.

A failure counts against the restart that started the game session it happened in. A failure the old session still reports in its last seconds, after the next restart was already charged, does not refund that next charge. While the spot stays blocked, the game retries roughly every minute and a half. The log and your actions get only the first failure of each restart, not every retry.

If you want to know when it happens, hook an action onto the event subscription_spawn_failed under Actions — a Discord message to the player or to your team, for example.

Permissions and access rights​

  • Shop catalog maintenance uses itemsets.view, itemsets.edit, itemsets.delete.
  • Order operations use orders.view, orders.create, orders.refund, orders.change, orders.redeliver.
  • Transaction overview uses transactions.view. Balance changes on player details use players.change_money.
  • Subscription maintenance uses subscriptions.view_active, subscriptions.create_active, subscriptions.edit_active, subscriptions.delete_active, subscriptions.view_available, subscriptions.create_available, subscriptions.edit_available, subscriptions.delete_available.
  • Player-facing subscription usage is separate: subscriptions.use.

Make sure role templates include the required action-level rights, not just broad section visibility.