Skip to main content

Shop system

This page explains how the shop works from an operational perspective: what players can buy, what admins manage, and how delivery and follow-up actions behave.

For audience-specific guides, also read:

Scope and availability​

  • Some subscription-related actions use separate permissions from item purchase actions.

Key access rights used across shop workflows:

  • player shopping: shop.access, shop.checkout, optional shop.see_unavailable
  • shop administration: itemsets.*, orders.*
  • subscription flows: subscriptions.use (player), subscriptions.view_active / subscriptions.edit_active / subscriptions.view_available (admin)

Core parts​

  • Catalog and categories
    • Players browse item categories and item sets.
    • If a server has no item categories, the catalog falls back to a flat item-set list without category navigation.
    • If categories exist, uncategorized item sets are grouped into an Uncategorized section.
    • Availability and purchase limits can differ per player/group.
  • Orders
    • Orders are created at checkout and move through status changes (pending, delivered, refunded, canceled).
  • Subscriptions
    • Subscription offers can be activated and managed over time.
    • Subscriptions can belong to players or factions.

Order lifecycle​

  1. Player (or admin) creates an order.
  2. Order stays pending until the next dzbot-managed restart, or — if the player scheduled it for later — until the first restart at or after the time they picked.
  3. During restart, pending deliveries are processed.
  4. After successful processing, pending orders are marked delivered.
  5. If processing fails, the order is not falsely marked as delivered.

Important behavior:

  • Canceled orders are not delivered.
  • Delivery is tied to dzbot-managed restarts, not to browsing or checkout.
  • Shop items do not survive a restart, so players can schedule an order for a later restart and pick their items up while they are online. At checkout they either take one of the upcoming restarts or enter their own date and time, up to seven days ahead. The chosen moment is a lower bound, not an exact appointment: the first restart at or after it delivers the order. Turn this off per server with Let players schedule shop orders under Settings → Economy.
  • For the same reason a vehicle doesn't belong in an item set: it can't be picked up, so it is gone after the next restart. Vehicles are sold as spawn subscriptions — see Vehicles belong in subscriptions.
  • Scheduled orders still charge at checkout and count towards purchase limits right away, and they can be canceled like any other pending order.

Subscription lifecycle​

  1. Players or admins create/update subscriptions.
  2. Active subscriptions are applied during restart cycles.
  3. Paid subscriptions are charged according to server configuration.
  4. If an apply cycle fails, safety mechanisms prevent inconsistent charging/delivery states.

Refund and redelivery model​

  • Player cancel (self-service)
    • Allowed only before delivery.
    • Full order amount is refunded to player balance.
  • Admin refund
    • Allowed only for delivered, non-canceled orders.
    • Can be partial by item quantity.
  • Admin redelivery
    • Allowed only for delivered orders.
    • Creates a follow-up delivery for eligible quantities.

Operational note about restarts​

If your community depends on shop delivery, restart operations should be run through dzbot. This keeps delivery and subscription handling consistent.

For consistent delivery and cleanup, execute manual and scheduled restarts through dzbot. Avoid mixing restart tools for shop-critical servers.