# Phoenix Shop documentation

> GUI shop plugin for Spigot and Paper: admin GUI shops, sell menus, player chest shops, sign shops and NPC shopkeepers, built and priced in-game, with or without Vault.

Docs: https://www.phoenixplugins.com/docs/phoenix-shop
Supported Minecraft versions: 1.20.4 – 26.3 (Spigot, Paper, Folia (experimental))

---

# 💸 AutoSell

## Information

The AutoSell add-on sells what a player is carrying on a timer, so they can keep mining or farming without opening a shop. Players run on autosell time that an admin hands out, and the add-on also adds placeable sell chests that empty themselves into your shops for as long as they have time left.

<figure><img src="../../.gitbook/assets/autosell/autosell.png" alt="" width="563"><figcaption><p>Editor (Autosell)</p></figcaption></figure>

Every sale goes through the normal sell path, so prices, currencies, stock, conditions, actions and sell multipliers such as the Sell Boosters add-on all apply exactly as they do in the shop menu.

## Installation

To install this add-on, drag and drop the jar file into the PhoenixShop/addons folder, then restart your server.

> **Info:**
The add-on requires the Premium edition. On Lite it does not load and the console says why.

## Files

| File | What it holds |
| ---- | ------------- |
| `PhoenixShop/addons/AutoSell/config.yml` | The add-on settings and the sell chest types. |
| Plugin database | Each player's autosell time, toggle and earnings, and every placed sell chest. An old `autosell.yml` is moved there on first start. |
| `PhoenixShop/translations/translations.<lang>.yml` | The add-on messages, under the `autosell` and `sellchest` sections. |

## How it works

Once autosell is on, the player's main inventory is sold every few seconds into the shops set in the [settings](#settings). Armor and the off-hand slot are left alone. Items a shop does not buy stay in the inventory.

Autosell time only counts down while the player is online with autosell on. When it runs out, autosell turns itself off and the player is told. A player with the unlimited permission never runs out.

Turning autosell on resets the earnings of the current session, which is what the action bar and the session placeholders show.

## Commands

| Command | Description |
| ------- | ----------- |
| `/autosell` | Turns autosell on or off. Same as `/autosell toggle`. Refused when the player has no time left. |
| `/pshop autosell add <player> <time>` | Gives a player autosell time. The player is told when they are online. |
| `/pshop autosell remove <player> <time>` | Takes autosell time away, down to zero. |
| `/pshop autosell set <player> <time>` | Sets a player's autosell time. |
| `/pshop autosell check [player]` | Shows how much autosell time is left. Without a player it shows your own. |
| `/pshop sellchest give <player> <type> [amount]` | Gives placeable sell chests of a type. The amount goes from 1 to 64. |

Times are written as a number and a unit: `30s`, `30m`, `6h` or `1d`. Units can be combined, such as `1h30m`.

A player has to have joined once, while the add-on was installed, before an offline name is accepted.

## Permissions

| Permission | What it allows | Default |
| ---------- | -------------- | ------- |
| `phoenixshop.autosell` | Using `/autosell`. | Nobody |
| `phoenixshop.autosell.infinite` | Autosell never runs out of time. | Nobody |
| `phoenixshop.command.autosell` | Adding, removing, setting and checking other players' autosell time. | Operators |
| `phoenixshop.command.sellchest` | Giving sell chests. | Operators |
| `phoenixshop.sellchest.unlimited` | Placing any number of sell chests. | Nobody |
| `phoenixshop.sellchest.limit.<n>` | Placing up to `<n>` sell chests, such as `phoenixshop.sellchest.limit.10`. With several, the highest counts. Without one, Chests per Player applies. | Nobody |

`phoenixshop.admin` grants all of the above. A shop with its own permission is only sold into for players who have it.

## Settings

> **Info:**
These settings live in addons/AutoSell/config.yml. **Editor > Add-ons > AutoSell** opens two screens: **Autosell**, with the settings below, and **Sell Chests**, covered on the [Sell Chests](sell-chests.md) page. Without the add-on, that button shows that the add-on is required.

### Action Bar

Shows the time left, the money earned this session and the current sell multiplier on the action bar of every player with autosell on. On by default.

<figure><img src="../../.gitbook/assets/autosell/action-bar.png" alt="" width="563"><figcaption><p>Settings (Action Bar)</p></figcaption></figure>

### Sell Interval

How many seconds pass between one sale and the next, for both a player's inventory and their sell chests. The default is 30, and the value goes from 1 to 3600. A lower value empties inventories sooner but runs more sales.

<figure><img src="../../.gitbook/assets/autosell/sell-interval.png" alt="" width="563"><figcaption><p>Settings (Sell Interval)</p></figcaption></figure>

### Shops

The shops autosell may sell into, in order. When an item sells in more than one of them, the shop higher in the list gets it. A shop that is turned off, or that has a permission the player lacks, is skipped for that player.

<figure><img src="../../.gitbook/assets/autosell/shops.png" alt="" width="563"><figcaption><p>Settings (Shops)</p></figcaption></figure>

Clicking it opens the list, where shops can be added to the bottom and two shops can swap places.

## Placeholders

| Placeholder | Description |
| ----------- | ----------- |
| %phoenixshop_autosell_enabled% | `true` when the player has autosell on, otherwise `false`. |
| %phoenixshop_autosell_earned_total% | Everything the player has earned from autosell and their sell chests, formatted per currency. |
| %phoenixshop_autosell_earned_total_raw% | The same total as a plain number, with every currency added together. |
| %phoenixshop_autosell_earned_session% | What the player has earned since autosell was last turned on, formatted per currency. |
| %phoenixshop_autosell_earned_session_raw% | The same session total as a plain number. |
| %phoenixshop_autosell_multiplier% | The player's current sell multiplier. `1.0` while offline. |
| %phoenixshop_autosell_time_remaining% | The autosell time the player has left. |
| %phoenixshop_autosell_time_remaining_hours% | The whole hours left. |
| %phoenixshop_autosell_time_remaining_minutes% | The minutes left past the whole hours. |
| %phoenixshop_autosell_time_remaining_seconds% | The seconds left past the whole minutes. |

The time placeholders show the unlimited label for a player with `phoenixshop.autosell.infinite`.

> **Info:**
The session earnings only count the player's inventory. Sell chest earnings go into the total and into each chest's own hologram.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/autosell

---

# 📜 Placeholders

## PlaceholderAPI Placeholders

| Placeholder | Description |
| ----------- | ----------- |
| %phoenixshop_autosell_enabled% | `true` when the player has autosell on, otherwise `false`. |
| %phoenixshop_autosell_earned_total% | Everything the player has earned from autosell and their sell chests, formatted per currency. |
| %phoenixshop_autosell_earned_total_raw% | The same total as a plain number, with every currency added together. |
| %phoenixshop_autosell_earned_session% | What the player has earned since autosell was last turned on, formatted per currency. |
| %phoenixshop_autosell_earned_session_raw% | The same session total as a plain number. |
| %phoenixshop_autosell_multiplier% | The player's current sell multiplier. `1.0` while offline. |
| %phoenixshop_autosell_time_remaining% | The autosell time the player has left. |
| %phoenixshop_autosell_time_remaining_hours% | The whole hours left. |
| %phoenixshop_autosell_time_remaining_minutes% | The minutes left past the whole hours. |
| %phoenixshop_autosell_time_remaining_seconds% | The seconds left past the whole minutes. |

The time placeholders show the unlimited label for a player with `phoenixshop.autosell.infinite`.

> **Info:**
The session earnings only count the player's inventory. Sell chest earnings go into the total and into each chest's own hologram.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/autosell/placeholders

---

# 📦 Sell Chests

> **Info:**
The sell chest settings and types live in addons/AutoSell/config.yml, and every one of them can be changed from **Sell Chests**, behind **Editor > Add-ons > AutoSell**.

## Sell Chests

A sell chest is a container a player places that sells whatever is put inside it. It is handed out as an item with `/pshop sellchest give` or with shift + right-click on a type in the editor, and each type sells for its own duration.

<figure><img src="../../.gitbook/assets/sell-chests/sell-chests.png" alt="" width="563"><figcaption><p>Autosell (Sell Chests)</p></figcaption></figure>

A sell chest does not need autosell time or the autosell permission. It has its own time, which starts from the type's duration when first placed.

## When it sells

Every sell interval, the chest's contents are sold into the same shops as autosell, checked against the owner's shop permissions. The earnings go to the owner.

The chest only sells, and its time only counts down, while the owner is online and the chest's chunk is loaded. When the time runs out, the owner is told and it turns into a normal chest: it stops selling, its hologram goes and its contents stay inside.

## Protection

| Action | Result |
| ------ | ------ |
| Opening | Only the owner and players with `phoenixshop.admin` can open it. |
| Breaking | Only the owner and admins can break it. With time left, it drops as a sell chest item that keeps the remaining time and its name. Without time left, it breaks like a normal chest. Either way its contents drop like a normal chest's, except in a shulker box sell chest, whose item keeps them inside. |
| Explosions and fire | The chest is never destroyed. |
| Pistons | Pistons cannot push or pull it. |
| Hoppers | Hoppers cannot pull items out of it, but can still fill it. |
| Claims | With Require Claim on, a sell chest can only be placed inside a WorldGuard, GriefPrevention, Lands or Towny claim the player can build in. Admins are not limited. |
| Placing a chest next to it | The two never join into a double chest. |

## Chest Menu

The owner opens the chest's menu by shift + right-clicking it. A normal right-click opens the chest as usual. Admins can open the menu of any chest, the same way or from [Placed Chests](#placed-chests).

### Hologram

Shows the chest's name, time left and total earnings above it. On for a new chest. The lines come from the translations file.

<figure><img src="../../.gitbook/assets/sell-chests/hologram.png" alt="" width="563"><figcaption><p>Sell Chest (Hologram)</p></figcaption></figure>

### Information

Shows the chest's owner, time left and total earnings. Time left and earnings update every second while the menu is open.

<figure><img src="../../.gitbook/assets/sell-chests/information.png" alt="" width="563"><figcaption><p>Sell Chest (Information)</p></figcaption></figure>

### Filter Mode

Decides what the **Items** list means. **Blacklist**, the default, never sells the listed items. **Whitelist** sells only the listed items. Clicking it swaps between the two.

<figure><img src="../../.gitbook/assets/sell-chests/filter-mode.png" alt="" width="563"><figcaption><p>Sell Chest (Filter Mode)</p></figcaption></figure>

### Items

The items the filter mode applies to. Left-click adds the item in your hand, right-click removes the last one and shift + right-click clears the list. A custom item from a supported item plugin is told apart from its base material, so filtering a custom fish leaves plain cod alone.

<figure><img src="../../.gitbook/assets/sell-chests/items.png" alt="" width="563"><figcaption><p>Sell Chest (Items)</p></figcaption></figure>

## Enabled

Turns sell chests on or off for the whole server. While off, a sell chest cannot be placed and the ones already placed stop selling and keep their time. On by default.

<figure><img src="../../.gitbook/assets/sell-chests/enabled.png" alt="" width="563"><figcaption><p>Sell Chests (Enabled)</p></figcaption></figure>

## Chests per Player

How many sell chests one player can have placed at the same time. The default is 3, and the value goes from 0 to 1000. Players with `phoenixshop.sellchest.unlimited` or `phoenixshop.admin` are not limited, and `phoenixshop.sellchest.limit.<n>` gives a player their own limit instead.

<figure><img src="../../.gitbook/assets/sell-chests/chests-per-player.png" alt="" width="563"><figcaption><p>Sell Chests (Chests per Player)</p></figcaption></figure>

## Require Claim

Only lets a sell chest be placed inside a claim the player can build in, checked with WorldGuard, GriefPrevention, Lands or Towny, whichever are installed. Off by default. With none of them installed, it has no effect. Players with `phoenixshop.admin` are not limited.

<figure><img src="../../.gitbook/assets/sell-chests/require-claim.png" alt="" width="563"><figcaption><p>Sell Chests (Require Claim)</p></figcaption></figure>

## Types

Lists every sell chest type by name and id, with its duration and whether it is enabled. Left-click edits a type, right-click deletes it after a confirmation and shift + left-click gives you one. A type with a duration that cannot be read is marked with an error and cannot be handed out.

<figure><img src="../../.gitbook/assets/sell-chests/types.png" alt="" width="563"><figcaption><p>Sell Chests (Types)</p></figcaption></figure>

**New Type** creates a chest that sells for one hour with the next free id, such as `sell_chest_1`, which is what `/pshop sellchest give` takes, and opens its editor straight away.

| Option | What it does |
| ------ | ------------ |
| Identifier | The id `/pshop sellchest give` takes. Placed chests follow a new id; chests already handed out keep the old one and can no longer be placed. |
| Display Name | The name of the chest item, and the name a placed chest uses in its hologram and messages. A placed chest keeps the name it was placed with. |
| Material | The block that is placed: a chest, a trapped chest or a barrel. Chests already handed out keep their block. |
| Duration | How long a chest sells for, written like `30m`, `6h`, `1d` or `1h30m`. A chest takes it when first placed, so placed and picked-up chests keep their time. |
| Lore | The item lore. `%time%` shows the time left. Chests already handed out keep their lore. |
| Enabled | Turns the type on or off. While off, it cannot be given or placed, and placed chests of it stop selling and keep their time. |
| Delete | Deletes the type. Chests of it already handed out can no longer be placed, and placed ones keep selling but break like a normal chest. |

## Placed Chests

Lists every sell chest placed on the server with its owner, type, time left, earnings and location. Left-click opens the chest's menu, shift + left-click teleports you in front of it and right-click removes it after a confirmation. Removing only stops it being a sell chest: the block and its items stay as a normal container.

<figure><img src="../../.gitbook/assets/sell-chests/placed-chests.png" alt="" width="563"><figcaption><p>Sell Chests (Placed Chests)</p></figcaption></figure>

The search keeps the chests whose owner or type contains the text, and `-` clears it. The sort shows the newest or the oldest first, or orders them by owner. A chest that is out of time, or whose type was deleted, is marked.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/autosell/sell-chests

---

# ⚙️ Settings

> **Info:**
These settings live in addons/AutoSell/config.yml. The **Autosell** button on the main editor menu opens two screens: **Autosell**, with the settings below, and **Sell Chests**, covered on the [Sell Chests](sell-chests.md) page. Without the add-on, that button shows that the add-on is required.

## Action Bar

Shows the time left, the money earned this session and the current sell multiplier on the action bar of every player with autosell on. On by default.

<figure><img src="../../.gitbook/assets/autosell/action-bar.png" alt="" width="563"><figcaption><p>Settings (Action Bar)</p></figcaption></figure>

## Sell Interval

How many seconds pass between one sale and the next, for both a player's inventory and their sell chests. The default is 30, and the value goes from 1 to 3600. A lower value empties inventories sooner but runs more sales.

<figure><img src="../../.gitbook/assets/autosell/sell-interval.png" alt="" width="563"><figcaption><p>Settings (Sell Interval)</p></figcaption></figure>

## Shops

The shops autosell may sell into, in order. When an item sells in more than one of them, the shop higher in the list gets it. A shop that is turned off, or that has a permission the player lacks, is skipped for that player.

<figure><img src="../../.gitbook/assets/autosell/shops.png" alt="" width="563"><figcaption><p>Settings (Shops)</p></figcaption></figure>

Clicking it opens the list, where shops can be added to the bottom and two shops can swap places.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/autosell/settings

---

# 🆕 Custom Add-ons

Custom add-ons are jars you write yourself that PhoenixShop loads from its addons folder, the same way it loads its own add-ons. Like every add-on, they load on Premium only.

## Maven Dependency

```xml
<repositories>
  <repository>
    <id>phoenix</id>
    <url>https://repo.phoenixplugins.com/repository/maven-public/</url>
  </repository>
</repositories>
```

```xml
<dependency>
  <groupId>com.phoenixplugins.sdk</groupId>
  <artifactId>api</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>com.phoenixplugins.phoenixshop</groupId>
  <artifactId>api</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <scope>provided</scope>
</dependency>
```

The first gives you the add-on base class, the second the shop API.

## Relocation

The PhoenixShop jar relocates the SDK, so your add-on has to point at the same package or it will not find the base class. Add the shade plugin with this relocation, without bundling anything:

```xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <artifactSet>
          <includes>
            <include>${project.groupId}:${project.artifactId}</include>
          </includes>
        </artifactSet>
        <relocations>
          <relocation>
            <pattern>com.phoenixplugins.sdk</pattern>
            <shadedPattern>com.phoenixplugins.phoenixshop.sdk</shadedPattern>
          </relocation>
        </relocations>
      </configuration>
    </execution>
  </executions>
</plugin>
```

## addon.yml

Create an `addon.yml` file in your project resources folder.

```yaml
name: AddonName
main: your.path.AddonExample
version: 1.0.0
description: Small description (optional)
color: "#3fb950"
```

| Field | Required | What it does |
| ----- | -------- | ------------ |
| `name` | Yes | The name of the add-on. Spaces are turned into underscores, and it names the add-on's data folder. |
| `main` | Yes | The full path to your class that extends `Addon`. |
| `version` | Yes | The version of your add-on. |
| `description` | No | A short description. |
| `color` | No | A hex color for the add-on's name in the console. |

## Main Class

```java
package your.path;

import com.phoenixplugins.phoenixshop.api.PhoenixShopAPI;
import com.phoenixplugins.sdk.api.plugin.addons.Addon;

public class AddonExample extends Addon {

    @Override
    public void init() {
    }

    @Override
    public void load() throws Exception {
    }

    @Override
    public void unload() {
    }

    @Override
    public void reload() throws Exception {
        unload();
        load();
    }

    @Override
    public String getRequiredPluginVersion() {
        return "1.0.0";
    }
}
```

| Method | When it runs |
| ------ | ------------ |
| `init` | Once, when the jar is read, before the plugin registers its hooks. Throwing here stops the add-on from loading. |
| `load` | When the plugin starts, and again on every `/pshop reload`. Register commands, listeners and tasks here. |
| `unload` | When the plugin stops, and before every reload. Undo everything `load` did. |
| `reload` | Not called by the plugin, which runs `unload` and then `load` instead. Point it at the same two so the add-on behaves the same either way. |
| `getRequiredPluginVersion` | The lowest PhoenixShop version the add-on runs on. On an older version it refuses to load. |

`getDataFolder()` returns the add-on's own folder, and `getResource(name)` reads a file out of your jar, which is how an add-on writes its default config on first start. `PhoenixShopAPI.getShopsManager()` gives you the shops.

## Events

The API module also carries Bukkit events, which any plugin can listen to, add-on or not, on Lite and Premium.

| Event | Fired | Cancellable |
| ----- | ----- | ----------- |
| `ShopPreTransactionEvent` | Before a buy or sell in a shop menu. The price can be changed. | Yes |
| `ShopTransactionEvent` | After a buy or sell in a shop menu went through. | No |
| `ShopEditEvent` | After a change made in the editor. | No |
| `PlayerShopCreateEvent` | When a chest shop is made. | No |
| `PlayerShopRemoveEvent` | When a chest shop is removed. | No |
| `PlayerShopPreTradeEvent` | Before a chest shop trade, once every check has passed and right before money or items move. | Yes |
| `PlayerShopTradeEvent` | After a chest shop trade went through. | No |

Cancelling `PlayerShopPreTradeEvent` stops the trade with nothing moved and nothing said to the player, so send your own message if they should know why. With [Click Confirm](../main-features/player-shops/settings.md#click-confirm) on, it also fires on the click that only asks the player to confirm, and cancelling it there skips the question.

Both chest shop trade events fire on the server thread (the shop's region thread on Folia) and carry:

| Getter | What it holds |
| ------ | ------------- |
| `getPlayer()` | The customer. |
| `getOwner()`, `getOwnerName()` | The shop's owner. |
| `getShopId()`, `getLocation()` | The shop's id and its sign. |
| `getKind()` | `BUY` when the customer buys, `SELL` when they sell. |
| `getItem()` | A copy of one of the traded item. |
| `getAmount()` | How many items change hands. |
| `getPrice()` | The total, in the currency or in payment items. |
| `getCurrency()` | The currency id, or `null` on a shop paid in an item. |
| `getPaymentItem()`, `paysInItems()` | A copy of the payment item on a shop paid in an item, otherwise `null`. |
| `isAdmin()` | Whether it is an admin shop. |
| `isRemote()` | Whether the customer traded from the shop list or find menu instead of at the sign. |
| `getMode()`, `getBuyPrice()`, `getSellPrice()` | The shop's mode and its prices per Amount. |

## Install

1. Build the jar with your usual build command.
2. Move it into the PhoenixShop/addons folder.
3. Restart the server.
4. Check the console for `Enabling addon` followed by your add-on's name.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/custom-addons

---

# 🌐 Network

## Information

The Network add-on makes every server on the same database count one shared stock. Without it, each server keeps its own count, so an item limited to 10 could be bought 10 times on every server. With it, the stock of an item and each player's purchase limit are counted once across the whole network.

The count is checked and taken in one database step, so two servers can never both sell the last one.

## Installation

To install this add-on, drag and drop the jar file into the PhoenixShop/addons folder of **every** server that should share stock, then restart them.

> **Warning:**
The add-on requires the Premium edition and a shared MySQL or MariaDB database. It refuses to load on Lite, and on a server that is still on SQLite. See [Setup](#setup).

## Files

The add-on has no files or settings of its own. It uses the database already set in the plugin's config.

## What is shared

| Shared | Not shared |
| ------ | ---------- |
| How many of a stocked item are left. | Shops, prices and every other setting. Each server reads its own shop files. |
| How many of an item each player has bought against its player limit. | |
| Restocking. The server that notices first refills the stock for everyone. | |

The restock countdown is not shown to players while the add-on is running.

## Setup

### Database

Every server has to point at the same database, with the same name and the same table prefix, in the `database` section of the plugin's config:

```yaml
database:
  type: mysql
  address: localhost
  name: phoenixshop_db
  port: 3306
  username: phoenixuser
  password: phoenixpassword
  table-prefix: ps
```

The type can be `mysql` or `mariadb`. On `sqlite`, the default, the add-on refuses to load and the console says to switch, since a file on one server has nothing to share.

### Shop files

Stock is matched between servers by the shop, category and item identifiers. Copy the same shop files to every server, or an item named differently on two servers is counted as two items.

### When the database is unreachable

If the database cannot be reached when the server starts, the add-on does not load and each server counts its own stock again.

If the connection drops while running, items with a stock or a player limit cannot be bought until the database answers again. This stops a player from hopping to another server to get past a limit. Items without a stock or limit are not affected.

### Removing it

Taking the jar out of a server's addons folder puts that server back on its own count.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/network

---

# ⚙️ Setup

## Database

Every server has to point at the same database, with the same name and the same table prefix, in the `database` section of the plugin's config:

```yaml
database:
  type: mysql
  address: localhost
  name: phoenixshop_db
  port: 3306
  username: phoenixuser
  password: phoenixpassword
  table-prefix: ps
```

The type can be `mysql` or `mariadb`. On `sqlite`, the default, the add-on refuses to load and the console says to switch, since a file on one server has nothing to share.

## Shop files

Stock is matched between servers by the shop, category and item identifiers. Copy the same shop files to every server, or an item named differently on two servers is counted as two items.

## When the database is unreachable

If the database cannot be reached when the server starts, the add-on does not load and each server counts its own stock again.

If the connection drops while running, items with a stock or a player limit cannot be bought until the database answers again. This stops a player from hopping to another server to get past a limit. Items without a stock or limit are not affected.

## Removing it

Taking the jar out of a server's addons folder puts that server back on its own count.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/network/setup

---

# 🧑‍🌾 NPC Shops

## Information

The NPC Shops add-on puts a shop on an NPC. Players right-click the NPC to open the shop, with the same permission and currency checks as opening it by command. The NPC can be any entity, and a villager opens a vanilla trade menu instead of the shop menu.

<figure><img src="../../.gitbook/assets/npc-shops/npc-shops.png" alt="" width="563"><figcaption><p>Editor (NPC Shops)</p></figcaption></figure>

## Installation

To install this add-on, drag and drop the jar file into the PhoenixShop/addons folder, then restart your server.

Without the add-on, its editor screens can still be browsed from the main editor as a locked preview. Nothing in the preview can be changed.

> **Info:**
The add-on is free, but it requires the Premium edition. On Lite it does not load and the console says why.

> **Warning:**
Without any NPC plugin, NPCs are plain mobs. [Citizens](https://www.spigotmc.org/resources/citizens.13811/), [FancyNpcs](https://modrinth.com/plugin/fancynpcs), ModelEngine and BetterModel add their own [engines](#engines). An NPC set to an engine that is not installed is not spawned.

## Files

| File | What it holds |
| ---- | ------------- |
| Plugin database | Every placed NPC. An old `npcs.yml` is moved there on first start and renamed `npcs.yml.migrated`. |
| `PhoenixShop/translations/translations.<lang>.yml` | The add-on messages, under the `npc` section. |

## Commands

| Command | Description |
| ------- | ----------- |
| `/shopnpc create <shop> [engine] [entity]` | Places an NPC for a shop on the block you are looking at. |
| `/shopnpc remove` | Removes the NPC you are looking at. |
| `/shopnpc list` | Lists every placed NPC with its shop, engine and position. An NPC whose shop no longer exists is marked as missing. |

`/npcshop` works as an alias. The commands have to be run by a player.

## Permissions

| Permission | What it allows |
| ---------- | -------------- |
| `phoenixshop.npcshops.manage` | Creating, removing and listing shop NPCs. |

Using an NPC needs no permission of its own. A shop with a permission only opens for players who have it.

## Creating an NPC

### Placing an NPC

**Editor > NPC Shops > New NPC** asks for a shop, then spawns the NPC where you stand, facing the way you face. It uses Citizens if it is installed, then FancyNpcs, and otherwise a plain villager.

<figure><img src="../../.gitbook/assets/npc-shops/placing-an-npc.png" alt="" width="563"><figcaption><p>NPC Shops (New NPC)</p></figcaption></figure>

The same can be done with a command. Look at the block the NPC should stand on, within 6 blocks, and run:

```
/shopnpc create <shop> [engine] [entity]
```

| Argument | What it does |
| -------- | ------------ |
| `shop` | The identifier of the shop the NPC opens. |
| `engine` | `citizens`, `fancynpcs`, `entity`, `modelengine` or `bettermodel`. Citizens when left out. |
| `entity` | Any living entity type, such as `villager` or `zombie`. A player when left out, or a villager on the `entity` engine. |

The NPC spawns on top of that block, facing you, with the shop's display name above it. It is named after the shop with a number, such as `shop-1`.

### Engines

| Engine | Requires | What it draws |
| ------ | -------- | ------------- |
| Entity | Nothing | A real mob with its AI turned off. Any living entity. |
| Citizens | Citizens | Any living entity, or a player with a skin. |
| FancyNpcs | FancyNpcs | Any living entity, or a player with a skin. |
| Model Engine | ModelEngine 4.0.9+ | A model, with an idle and an interaction animation. |
| BetterModel | BetterModel | A model, with an idle and an interaction animation. |

<figure><img src="../../.gitbook/assets/npc-shops/engines.png" alt="" width="563"><figcaption><p>Edit NPC (Engine)</p></figcaption></figure>

The add-on keeps its own record of every NPC and spawns them again on each start, so they are not saved in the Citizens or FancyNpcs files. Changes made to them through those plugins are lost on the next restart.

An NPC that is moved or pushed is put back in place.

### Editing an NPC

**Editor > NPC Shops** lists every NPC, and marks the ones whose shop is gone or whose engine is not installed. Every change respawns the NPC straight away.

<figure><img src="../../.gitbook/assets/npc-shops/editing-an-npc.png" alt="" width="563"><figcaption><p>NPC Shops (rotating-1)</p></figcaption></figure>

| Field | What it does |
| ----- | ------------ |
| Shop | The shop the NPC opens. |
| Nameplate | The lines shown above the NPC. |
| Engine | Swaps between the installed engines. Its settings are listed below. |
| Scale | Makes the NPC bigger or smaller, 0.1 to 10. |
| Glow | A coloured outline around the NPC. |
| Position | Click a block: the NPC moves on top of it, facing you. |

#### Engine settings

| Setting | Engines | What it does |
| ------- | ------- | ------------ |
| Entity Type | Entity, Citizens, FancyNpcs | What the NPC is. A villager opens the [trade menu](#villager-trades). |
| Skin | Citizens, FancyNpcs | The skin of a player NPC, looked up from a Mineskin link, a player name or a UUID. |
| Look Close | All | Turns the NPC towards the nearest player within 8 blocks. |
| Model | Model Engine, BetterModel | The model the NPC shows. Until one is picked, nothing spawns. |
| Idle Animation | Model Engine, BetterModel | Loops while nobody is clicking. |
| Interaction Animation | Model Engine, BetterModel | Plays once each time a player clicks the NPC. |

### Removing an NPC

Delete it in the editor, or look at the block the NPC stands on and run `/shopnpc remove`.

<figure><img src="../../.gitbook/assets/npc-shops/removing-an-npc.png" alt="" width="563"><figcaption><p>Edit NPC (Delete)</p></figcaption></figure>

> **Info:**
Deleting the shop an NPC points at does not remove the NPC. Clicking it tells the player the shop is gone, and `/shopnpc list` marks it as missing.

## Villager Trades

An NPC with the `villager` entity type opens the vanilla trade menu instead of the shop menu. Every item of the shop that can be bought is listed as a trade, with the price that player pays, sales and discounts included, added to the bottom of its lore.

Clicking the result buys one purchase of the item, charged in the shop's currency like any other purchase. The cost slot shows a paper named after the currency, since money cannot be a vanilla trade item. The player cannot move items into the menu.

### What is left out

| Left out | Why |
| -------- | --- |
| Selling | A villager only sells to the player. Items can only be sold through the shop menu or the sell commands. |
| Disabled categories and items | They are hidden from the trade list, as in the shop menu. |

When the shop has nothing that can be bought, the menu does not open and the player is told.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/npc-shops

---

# ➕ Creating an NPC

## Placing an NPC

**Editor > NPC Shops > New NPC** asks for a shop, then spawns the NPC where you stand, facing the way you face. It uses Citizens if it is installed, then FancyNpcs, and otherwise a plain villager.

<figure><img src="../../.gitbook/assets/npc-shops/placing-an-npc.png" alt="" width="563"><figcaption><p>NPC Shops (New NPC)</p></figcaption></figure>

The same can be done with a command. Look at the block the NPC should stand on, within 6 blocks, and run:

```
/shopnpc create <shop> [engine] [entity]
```

| Argument | What it does |
| -------- | ------------ |
| `shop` | The identifier of the shop the NPC opens. |
| `engine` | `citizens`, `fancynpcs`, `entity`, `modelengine` or `bettermodel`. Citizens when left out. |
| `entity` | Any living entity type, such as `villager` or `zombie`. A player when left out, or a villager on the `entity` engine. |

The NPC spawns on top of that block, facing you, with the shop's display name above it. It is named after the shop with a number, such as `shop-1`.

## Engines

| Engine | Requires | What it draws |
| ------ | -------- | ------------- |
| Entity | Nothing | A real mob with its AI turned off. Any living entity. |
| Citizens | Citizens | Any living entity, or a player with a skin. |
| FancyNpcs | FancyNpcs | Any living entity, or a player with a skin. |
| Model Engine | ModelEngine 4.0.9+ | A model, with an idle and an interaction animation. |
| BetterModel | BetterModel | A model, with an idle and an interaction animation. |

<figure><img src="../../.gitbook/assets/npc-shops/engines.png" alt="" width="563"><figcaption><p>Edit NPC (Engine)</p></figcaption></figure>

The add-on keeps its own record of every NPC and spawns them again on each start, so they are not saved in the Citizens or FancyNpcs files. Changes made to them through those plugins are lost on the next restart.

An NPC that is moved or pushed is put back in place.

## Editing an NPC

**Editor > NPC Shops** lists every NPC, and marks the ones whose shop is gone or whose engine is not installed. Every change respawns the NPC straight away.

<figure><img src="../../.gitbook/assets/npc-shops/editing-an-npc.png" alt="" width="563"><figcaption><p>NPC Shops (rotating-1)</p></figcaption></figure>

| Field | What it does |
| ----- | ------------ |
| Shop | The shop the NPC opens. |
| Nameplate | The lines shown above the NPC. |
| Engine | Swaps between the installed engines. Its settings are listed below. |
| Scale | Makes the NPC bigger or smaller, 0.1 to 10. |
| Glow | A coloured outline around the NPC. |
| Position | Click a block: the NPC moves on top of it, facing you. |

### Engine settings

| Setting | Engines | What it does |
| ------- | ------- | ------------ |
| Entity Type | Entity, Citizens, FancyNpcs | What the NPC is. A villager opens the [trade menu](villager-trades.md). |
| Skin | Citizens, FancyNpcs | The skin of a player NPC, looked up from a Mineskin link, a player name or a UUID. |
| Look Close | All | Turns the NPC towards the nearest player within 8 blocks. |
| Model | Model Engine, BetterModel | The model the NPC shows. Until one is picked, nothing spawns. |
| Idle Animation | Model Engine, BetterModel | Loops while nobody is clicking. |
| Interaction Animation | Model Engine, BetterModel | Plays once each time a player clicks the NPC. |

## Removing an NPC

Delete it in the editor, or look at the block the NPC stands on and run `/shopnpc remove`.

<figure><img src="../../.gitbook/assets/npc-shops/removing-an-npc.png" alt="" width="563"><figcaption><p>Edit NPC (Delete)</p></figcaption></figure>

> **Info:**
Deleting the shop an NPC points at does not remove the NPC. Clicking it tells the player the shop is gone, and `/shopnpc list` marks it as missing.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/npc-shops/creating-an-npc

---

# 🔁 Villager Trades

## Villager Trades

An NPC with the `villager` entity type opens the vanilla trade menu instead of the shop menu. Every item of the shop that can be bought is listed as a trade, with the price that player pays, sales and discounts included, added to the bottom of its lore.

Clicking the result buys one purchase of the item, charged in the shop's currency like any other purchase. The cost slot shows a paper named after the currency, since money cannot be a vanilla trade item. The player cannot move items into the menu.

## What is left out

| Left out | Why |
| -------- | --- |
| Selling | A villager only sells to the player. Items can only be sold through the shop menu or the sell commands. |
| Disabled categories and items | They are hidden from the trade list, as in the shop menu. |

When the shop has nothing that can be bought, the menu does not open and the player is told.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/npc-shops/villager-trades

---

# 🔄 Rotating Shop

## Information

The Rotating Shop add-on makes any category of any shop rotate. The category keeps all of its items as a pool, and its menu only shows a few of them at a time, picked again on a schedule. Every player sees the same picks, and they survive a restart. See [Rotation](#rotation) for the settings.

The picked items are normal shop items: prices, stock, limits, requirements and actions all work as usual.

## Installation

To install this add-on, drag and drop the jar file into the PhoenixShop/addons folder, then restart your server.

> **Warning:**
The add-on requires the Premium edition. On Lite it refuses to load and the console names the jar to remove.

## Files

| File | What it holds |
| ---- | ------------- |
| `PhoenixShop/addons/RotatingShop/config.yml` | The rotating categories and their settings. |
| Plugin database | The items on sale now and when they change, so a restart picks nothing new. An old `data.yml` is moved there on first start. |
| `PhoenixShop/translations/translations.<lang>.yml` | The add-on messages, under the `rotatingshop` section. |

## Commands

| Command | Description |
| ------- | ----------- |
| `/rotatingshop list` | Lists every rotating category and when it changes next. |
| `/rotatingshop open <rotation> [player]` | Opens a rotating category. With a player, opens it for them. |
| `/rotatingshop rotate <rotation>` | Picks new items now and starts the timer again. |

`/rshop` works as an alias.

## Permissions

| Permission | What it allows |
| ---------- | -------------- |
| `phoenixshop.rotatingshop.open-others` | Opening a rotating category for another player. |
| `phoenixshop.rotatingshop.rotate` | Picking new items with `/rotatingshop rotate`. |

Opening a category for yourself needs whatever the shop and category require. A shop opened for another player skips that player's shop permission check.

## Placeholders

| Placeholder | Shows |
| ----------- | ----- |
| `%phoenixshop_rotation_<rotation>%` | The time until the rotation picks new items. |
| `%phoenixshop_rotation_<rotation>_seconds%` | The same, in seconds. |

## Updating from the single rotating shop

Older versions had one rotating shop of their own. On the first start with this version, it becomes a normal shop called `rotating` with one rotating category holding the whole pool, keeping its name, icon, permission, currency, cycle and shown count. The old settings file is kept as config.old.yml.

## Rotation

> **Info:**
Everything in this section is set in the shop and category editors and saved to addons/RotatingShop/config.yml.

### Making a category rotate

Open the category in the editor, click [Rotation](../../main-features/categories/edit-category.md#rotation) and turn **Rotating** on. Its items become the pool and the first picks go on sale straight away. Turning it off stops the rotation and shows every item of the category again.

[Rotations](../../main-features/shops/edit-shop.md#rotations) in the shop editor lists the rotating categories of that shop. Left-click one to edit it, right-click to stop it, and **Make a Category Rotate** picks another category of the shop.

A rotation follows the identifiers of its shop and category. After renaming either one, stop the rotation and make the category rotate again.

### Settings

| Setting | What it does |
| ------- | ------------ |
| Schedule | When new items are picked, see below. Changing it starts the timer again from now. |
| Items Shown | How many items of the pool are on sale at once, up to 54. 0, or more than the pool holds, shows all of them. Changing it picks new items straight away. |
| Can Repeat | On: every pick is random, and an item is never shown twice in one pick. Off: every item of the pool is shown once before any comes back. |
| Broadcast | Tells everyone online in the chat when new items are picked. |
| Chances | The chance of single items, see below. |
| Pick New Items | Picks new items now and starts the timer again. |

### Schedule

| Schedule | New items are picked |
| -------- | -------------------- |
| `daily` | At midnight. |
| `monthly` | At midnight on the first day of the month. |
| A length, such as `12h 30m 15s`, `90m` or `1w` | That long after the last pick. Units are `w`, `d`, `h`, `m` and `s`. After a restart it keeps the same rhythm instead of starting over. |
| A cron line, such as `0 0/30 * * * ?` | At every time it matches. |

Times follow the server's clock and time zone, and the add-on checks once a second. Cron lines take six fields (seconds first, `?` for the unused day field), an optional seventh for the year, or the five fields of a standard cron line. Lists, ranges, steps and the names `JAN`-`DEC` and `SUN`-`SAT` work, `L`, `W` and `#` do not. An hour of `24` means midnight. A schedule that cannot be read changes daily and says so in the console.

### Chances

Each item can have a percent chance of being picked. Items without one share what is left of 100% equally, so with one item at 40% in a pool of five, the other four have 15% each. Once the chances add up to 100% or more, the items without one are only picked to fill the slots the others leave. Disabled items are never picked. Setting a chance to 0 makes the item share again.

### Buying and selling

Only the items on sale can be bought, from the menu and from anywhere else that buys from the shop. Every item of the pool can still be sold with `/sell` and the other ways of selling into the shop. Stock and player limits keep their counts between picks, so an item that sold out is still sold out when it comes back.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/rotating-shop

---

# 🗓️ Rotation

> **Info:**
Everything on this page is set in **Editor > Rotating Shop** and saved to addons/RotatingShop/config.yml.

## Making a category rotate

**Make a Category Rotate** lists every category of every shop that does not rotate yet. Picking one makes its items the pool and puts the first picks on sale straight away. In the list, left-click a rotation to edit it and right-click to stop it, which shows every item of the category again.

A rotation follows the identifiers of its shop and category. After renaming either one, stop the rotation and make the category rotate again.

## Settings

| Setting | What it does |
| ------- | ------------ |
| Schedule | When new items are picked, see below. Changing it starts the timer again from now. |
| Items Shown | How many items of the pool are on sale at once, up to 54. 0, or more than the pool holds, shows all of them. Changing it picks new items straight away. |
| Can Repeat | On: every pick is random, and an item is never shown twice in one pick. Off: every item of the pool is shown once before any comes back. |
| Broadcast | Tells everyone online in the chat when new items are picked. |
| Chances | The chance of single items, see below. |
| Pick New Items | Picks new items now and starts the timer again. |

## Schedule

| Schedule | New items are picked |
| -------- | -------------------- |
| `daily` | At midnight. |
| `monthly` | At midnight on the first day of the month. |
| A length, such as `12h 30m 15s`, `90m` or `1w` | That long after the last pick. Units are `w`, `d`, `h`, `m` and `s`. After a restart it keeps the same rhythm instead of starting over. |
| A cron line, such as `0 0/30 * * * ?` | At every time it matches. |

Times follow the server's clock and time zone, and the add-on checks once a second. Cron lines take six fields (seconds first, `?` for the unused day field), an optional seventh for the year, or the five fields of a standard cron line. Lists, ranges, steps and the names `JAN`-`DEC` and `SUN`-`SAT` work, `L`, `W` and `#` do not. An hour of `24` means midnight. A schedule that cannot be read changes daily and says so in the console.

## Chances

Each item can have a percent chance of being picked. Items without one share what is left of 100% equally, so with one item at 40% in a pool of five, the other four have 15% each. Once the chances add up to 100% or more, the items without one are only picked to fill the slots the others leave. Disabled items are never picked. Setting a chance to 0 makes the item share again.

## Buying and selling

Only the items on sale can be bought, from the menu and from anywhere else that buys from the shop. Every item of the pool can still be sold with `/sell` and the other ways of selling into the shop. Stock and player limits keep their counts between picks, so an item that sold out is still sold out when it comes back.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/rotating-shop/rotation

---

# 🚀 Sell Boosters

## Information

The Sell Boosters add-on raises what players are paid when they sell. A booster runs for a set time and covers the whole server or a single player, and every category or only one. A [permission booster](#permission-boosters) lasts for as long as a player holds its permission, in every shop or only one shop, category or item. Boosters never change buying prices.

The add-on also holds the [price modifiers](#price-modifiers): groups that give players with a permission a different buy and sell price in every shop.

A booster applies to every sale made into a shop, including the ones made by the AutoSell and Sell Wands add-ons.

## Installation

To install this add-on, drag and drop the jar file into the PhoenixShop/addons folder, then restart your server.

> **Warning:**
The add-on requires the Premium edition. On Lite it refuses to load and the console names the jar to remove.

## Files

| File | What it holds |
| ---- | ------------- |
| `PhoenixShop/addons/SellBoosters/config.yml` | The add-on settings, the permission boosters and the price modifiers. |
| Plugin database | The boosters running now. An old `boosters.yml` is moved there on first start. |
| `PhoenixShop/translations/translations.<lang>.yml` | The add-on messages, under the `boosters` section. |

## Commands

| Command | Description |
| ------- | ----------- |
| `/sellbooster public <multiplier> <duration> [category]` | Starts a booster for everyone. |
| `/sellbooster private <player> <multiplier> <duration> [category]` | Starts a booster for one online player. |
| `/sellbooster stop <booster>` | Stops a running booster. |
| `/sellbooster list` | Lists the running boosters with their multiplier, who they cover, their category and the time left. |

`/sellboosters` works as an alias. See [Boosters](#boosters) for the arguments.

## Permissions

| Permission | What it allows |
| ---------- | -------------- |
| `phoenixshop.booster.manage` | Starting and stopping boosters. |

`/sellbooster list` needs no permission.

## Placeholders

The add-on has no placeholders of its own. The AutoSell multiplier placeholder shows the boosters that cover every category.

## Boosters

### Starting a booster

```
/sellbooster public 2 1h
/sellbooster private Steve 1.5 30m ores
```

| Argument | What it does |
| -------- | ------------ |
| `multiplier` | What sale prices are multiplied by. It has to be above 1, so `1.5` pays half as much again. |
| `duration` | How long it runs, written as a number and one unit: `90s`, `30m`, `6h` or `2d`. Units cannot be combined. |
| `category` | The identifier of a category. Only items in a category with that identifier, in any shop, are boosted. Left out, every category is. |

The booster is given an identifier, shown when it starts and in `/sellbooster list`, which is what `/sellbooster stop` takes.

A booster ends at a fixed time. It keeps running through a restart, and time the server is offline still counts.

### From the editor

**Editor > Sell Boosters > Running Boosters** lists every booster that is running, with who it applies to, its category and the time left. A booster can be stopped from there, and **Start Booster** starts a new one:

| Field | What it does |
| ----- | ------------ |
| Multiplier | Same as the command. Above 1. |
| Duration | Same as the command, except units can be combined, such as `1h30m`. |
| Player | An online player the booster is for. `none` makes it public. |
| Category | Same as the command. `none` boosts every category. |

### Settings

> **Info:**
Both settings are in addons/SellBoosters/config.yml, and can also be changed in **Editor > Sell Boosters**, where they apply straight away.

#### stacking

Decides what happens when more than one booster applies to the same sale.

| Value | Result |
| ----- | ------ |
| `MAX` | Only the biggest one counts. A 2x and a 1.5x pay 2x. The default. |
| `STACK` | They multiply. A 2x and a 1.5x pay 3x. |

#### action-bar

Shows the multiplier and time left on the action bar of every player a booster applies to. When several apply, the one that runs longest is shown. On by default.

## Permission Boosters

A permission booster raises what players with its permission are paid when they sell, for as long as they hold the permission. It can cover every shop, or only one shop, one category or one item. Buying prices are never changed.

The permission has to be given to the player. Operators do not get it just by being operators.

### Permission boosters in the editor

**Editor > Sell Boosters > Permission Boosters** lists every permission booster. **New Permission Booster** creates one, left-click edits it and right-click deletes it.

| Field | What it does |
| ----- | ------------ |
| Identifier | Its name in the list and in config.yml. |
| Permission | The permission a player needs. |
| Sell Percent | The percent of the sell price these players are paid. `150%` is a 50% bonus. |
| Shop | The identifier of a shop. Write `-` for every shop. |
| Category | The identifier of a category. Write `-` for every category. |
| Item | The identifier of an item. Write `-` for every item. |

### How they combine

Permission boosters follow the same stacking setting as running boosters. With `MAX`, the biggest multiplier among every running booster and every permission booster the player holds counts. With `STACK`, they all multiply. A permission booster below 100% lowers what the sale pays.

### Permission boosters in config.yml

```yaml
permission-boosters:
  vip:
    permission: sellboosters.vip
    multiplier: 1.5
    shop: ''
    category: ores
    item: ''
```

Imports from ShopGUI+ bring its sell price modifiers for one shop or one item across as permission boosters, keeping their `shopguiplus.pricemodifiers.<id>` permission. Imports from EconomyShopGUI do the same for its sell multipliers for one section, keeping their `EconomyShopGUI.sell-multipliers.<group>` permission.

## Price Modifiers

> **Info:**
Price modifiers are part of the Sell Boosters add-on and saved in its config.yml. Without the add-on, every player pays normal prices.

Each group pairs a permission with a buy and a sell percent, applied in every shop. The groups are set under **Editor > Sell Boosters > Price Modifiers**.

| Option | Description |
| --- | --- |
| Identifier | The group's name. |
| Permission | The permission that puts a player in the group. An empty permission applies to nobody. |
| Buy Percent | The share of the buy price the group pays, from 1 to 1000. 90% is a 10% discount. |
| Sell Percent | The share of the sell price the group is paid, from 1 to 1000. 110% pays 10% more. |

A new group is named `group_N`, with the permission `phoenixshop.modifier.group_N`, at 100% buy and 100% sell.

A player in several groups gets the lowest buy percent and the highest sell percent among them, which may come from different groups. A player in none pays normal prices.

> **Warning:**
The permission only counts when it is set on the player, directly or through a group in your permissions plugin. Being OP does not give it.

Groups still in the main plugin's config.yml from an older version are moved into the add-on's config.yml the first time the add-on starts.

### Where It Applies

The modified price is what the player is actually charged or paid, from the shop menus, `/sell`, the sell menu, AutoSell and sign shops. It is also the price shown in the category lore, the buy and sell menus, the bulk menus, the sell menu's worth, the search results and the Bedrock forms.

[Category and shop sales](../../main-features/categories/edit-category.md#sale) apply on top of the modifier.

Admin sign text is the same for everyone, so it keeps showing the normal price. A sign click that fills the inventory still buys as many as the player can afford at their own price.

[Boosters](#boosters) and [permission boosters](#permission-boosters) multiply on top of the modifier: a 110% sell percent and a 2x booster pay 2.2 times the sell price. The sell menu's worth shows the modified price without the booster.

### Strike-Through Price

When a player's buy price is lowered or sell price raised, the price placeholders in the menus show the normal price struck through next to the new one. The look is the `price.discounted-buy` and `price.discounted-sell` translations: the new price is red when buying and green when selling.

```yaml
en:
  price:
    discounted-buy: "&8&m%base%&c %price%"
    discounted-sell: "&8&m%base%&a %price%"
```

Bedrock forms show only the new price.

To place the normal price yourself, the menus also have a `_base` version of each price placeholder:

| Placeholder | Menus |
| --- | --- |
| %buy\_price\_base%, %sell\_price\_base% | Category, Search |
| %price\_base%, %unit\_price\_base% | Buy, Sell |
| %price\_base% | Bulk Buy, Bulk Sell |

### Price modifiers in config.yml

```yaml
price-modifiers:
  vip:
    permission: phoenixshop.modifier.vip
    buy: 0.9
    sell: 1.1
```

`buy` and `sell` are multipliers, so `0.9` is a 10% discount and `1.1` pays 10% more. The editor shows them as percents.

Imports from ShopGUI+ bring its global price modifiers across as groups, keeping their `shopguiplus.pricemodifiers.<id>` permission. Imports from EconomyShopGUI do the same for its discounts and sell multipliers under `all`. Without the add-on, they are left out and counted in the import report.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/sell-boosters

---

# ⚡ Boosters

## Starting a booster

```
/sellbooster public 2 1h
/sellbooster private Steve 1.5 30m ores
```

| Argument | What it does |
| -------- | ------------ |
| `multiplier` | What sale prices are multiplied by. It has to be above 1, so `1.5` pays half as much again. |
| `duration` | How long it runs, written as a number and one unit: `90s`, `30m`, `6h` or `2d`. Units cannot be combined. |
| `category` | The identifier of a category. Only items in a category with that identifier, in any shop, are boosted. Left out, every category is. |

The booster is given an identifier, shown when it starts and in `/sellbooster list`, which is what `/sellbooster stop` takes.

A booster ends at a fixed time. It keeps running through a restart, and time the server is offline still counts.

## From the editor

**Editor > Sell Boosters > Running Boosters** lists every booster that is running, with who it applies to, its category and the time left. A booster can be stopped from there, and **Start Booster** starts a new one:

| Field | What it does |
| ----- | ------------ |
| Multiplier | Same as the command. Above 1. |
| Duration | Same as the command, except units can be combined, such as `1h30m`. |
| Player | An online player the booster is for. `none` makes it public. |
| Category | Same as the command. `none` boosts every category. |

## Settings

> **Info:**
Both settings are in addons/SellBoosters/config.yml, and can also be changed in **Editor > Sell Boosters**, where they apply straight away.

### stacking

Decides what happens when more than one booster applies to the same sale.

| Value | Result |
| ----- | ------ |
| `MAX` | Only the biggest one counts. A 2x and a 1.5x pay 2x. The default. |
| `STACK` | They multiply. A 2x and a 1.5x pay 3x. |

### action-bar

Shows the multiplier and time left on the action bar of every player a booster applies to. When several apply, the one that runs longest is shown. On by default.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/sell-boosters/boosters

---

# 🔑 Permission Boosters

## Permission Boosters

A permission booster raises what players with its permission are paid when they sell, for as long as they hold the permission. It can cover every shop, or only one shop, one category or one item. Buying prices are never changed.

The permission has to be given to the player. Operators do not get it just by being operators.

## From the editor

**Editor > Sell Boosters > Permission Boosters** lists every permission booster. **New Permission Booster** creates one, left-click edits it and right-click deletes it.

| Field | What it does |
| ----- | ------------ |
| Identifier | Its name in the list and in config.yml. |
| Permission | The permission a player needs. |
| Sell Percent | The percent of the sell price these players are paid. `150%` is a 50% bonus. |
| Shop | The identifier of a shop. Write `-` for every shop. |
| Category | The identifier of a category. Write `-` for every category. |
| Item | The identifier of an item. Write `-` for every item. |

## How they combine

Permission boosters follow the same stacking setting as running boosters. With `MAX`, the biggest multiplier among every running booster and every permission booster the player holds counts. With `STACK`, they all multiply. A permission booster below 100% lowers what the sale pays.

## In config.yml

```yaml
permission-boosters:
  vip:
    permission: sellboosters.vip
    multiplier: 1.5
    shop: ''
    category: ores
    item: ''
```

Imports from ShopGUI+ bring its sell price modifiers for one shop or one item across as permission boosters, keeping their `shopguiplus.pricemodifiers.<id>` permission. Imports from EconomyShopGUI do the same for its sell multipliers for one section, keeping their `EconomyShopGUI.sell-multipliers.<group>` permission.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/sell-boosters/permission-boosters

---

# 🏷️ Price Modifiers

> **Info:**
Price modifiers are part of the Sell Boosters add-on and saved in its config.yml. Without the add-on, every player pays normal prices.

## Price Modifiers

Each group pairs a permission with a buy and a sell percent, applied in every shop. The groups are set under **Editor > Sell Boosters > Price Modifiers**.

| Option | Description |
| --- | --- |
| Identifier | The group's name. |
| Permission | The permission that puts a player in the group. An empty permission applies to nobody. |
| Buy Percent | The share of the buy price the group pays, from 1 to 1000. 90% is a 10% discount. |
| Sell Percent | The share of the sell price the group is paid, from 1 to 1000. 110% pays 10% more. |

A new group is named `group_N`, with the permission `phoenixshop.modifier.group_N`, at 100% buy and 100% sell.

A player in several groups gets the lowest buy percent and the highest sell percent among them, which may come from different groups. A player in none pays normal prices.

> **Warning:**
The permission only counts when it is set on the player, directly or through a group in your permissions plugin. Being OP does not give it.

Groups still in the main plugin's config.yml from an older version are moved into the add-on's config.yml the first time the add-on starts.

## Where It Applies

The modified price is what the player is actually charged or paid, from the shop menus, `/sell`, the sell menu, AutoSell and sign shops. It is also the price shown in the category lore, the buy and sell menus, the bulk menus, the sell menu's worth, the search results and the Bedrock forms.

[Category and shop sales](../../main-features/categories/edit-category.md#sale) apply on top of the modifier.

Admin sign text is the same for everyone, so it keeps showing the normal price. A sign click that fills the inventory still buys as many as the player can afford at their own price.

[Boosters](boosters.md) and [permission boosters](permission-boosters.md) multiply on top of the modifier: a 110% sell percent and a 2x booster pay 2.2 times the sell price. The sell menu's worth shows the modified price without the booster.

## Strike-Through Price

When a player's buy price is lowered or sell price raised, the price placeholders in the menus show the normal price struck through next to the new one. The look is the `price.discounted-buy` and `price.discounted-sell` translations: the new price is red when buying and green when selling.

```yaml
en:
  price:
    discounted-buy: "&8&m%base%&c %price%"
    discounted-sell: "&8&m%base%&a %price%"
```

Bedrock forms show only the new price.

To place the normal price yourself, the menus also have a `_base` version of each price placeholder:

| Placeholder | Menus |
| --- | --- |
| %buy\_price\_base%, %sell\_price\_base% | Category, Search |
| %price\_base%, %unit\_price\_base% | Buy, Sell |
| %price\_base% | Bulk Buy, Bulk Sell |

## In config.yml

```yaml
price-modifiers:
  vip:
    permission: phoenixshop.modifier.vip
    buy: 0.9
    sell: 1.1
```

`buy` and `sell` are multipliers, so `0.9` is a 10% discount and `1.1` pays 10% more. The editor shows them as percents.

Imports from ShopGUI+ bring its global price modifiers across as groups, keeping their `shopguiplus.pricemodifiers.<id>` permission. Imports from EconomyShopGUI do the same for its discounts and sell multipliers under `all`. Without the add-on, they are left out and counted in the import report.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/sell-boosters/price-modifiers

---

# 🪄 Sell Wands

## Information

The Sell Wands add-on adds a wand that sells everything in a container with one right-click. Prices are read from one of your shops, so currencies, stock, limits, conditions, actions and sell boosters all apply as they do in the shop menu. Items the shop does not buy stay in the container.

Each wand has a number of uses, or never runs out.

## Installation

To install this add-on, drag and drop the jar file into the PhoenixShop/addons folder, then restart your server.

> **Warning:**
The add-on requires the Premium edition. On Lite it refuses to load and the console names the jar to remove.

## Files

| File | What it holds |
| ---- | ------------- |
| `PhoenixShop/addons/SellWands/config.yml` | The shop the wand sells into, the containers it works on and the look of the wand. |
| `PhoenixShop/translations/translations.<lang>.yml` | The add-on messages, under the `sellwands` section. |

## Commands

| Command | Description |
| ------- | ----------- |
| `/sellwand give <player> [uses]` | Gives an online player a sell wand. Without `uses`, the default from the config is used. `-1` gives a wand that never runs out. |

`/sellwands` works as an alias.

## Permissions

| Permission | What it allows |
| ---------- | -------------- |
| `phoenixshop.sellwand.give` | Giving sell wands. |

Using a wand needs no permission of its own. When the wand's shop has a permission, only players who have it can use the wand.

## Wands

### Using a wand

Hold the wand in the main hand and right-click one of the listed containers. Everything in it that the shop buys is sold in one go and the player is told what they earned.

| Case | Result |
| ---- | ------ |
| Nothing in the container sells | No use is spent. |
| A region plugin blocks opening the container | The wand does nothing, so it cannot sell out of someone else's protected chest. |
| The container is not in the list | The click works as a normal right-click. |

The items pass through the player's inventory on their way to the shop, so a player with a full inventory cannot sell and is told so.

### Uses

Every right-click that sells something spends one use, and the uses left are shown in the wand's lore. A wand on its last use is gone once used. A wand with `-1` uses never runs out.

Wands are recognised by a hidden tag, not by their name or material, so renaming one in an anvil does not stop it working.

### Settings

> **Info:**
Everything below is set in addons/SellWands/config.yml. The add-on has no editor.

```yaml
shop: shop
uses: 50
containers:
  - CHEST
  - TRAPPED_CHEST
  - BARREL
  - SHULKER_BOX
wand:
  material: BLAZE_ROD
  display-name: '&6Sell Wand'
  lore:
    - '&7Right-click a container to sell'
    - '&7everything inside it.'
    - ''
    - '&fUses Left: &e%uses%'
  unlimited-label: '&aUnlimited'
```

| Option | What it does |
| ------ | ------------ |
| `shop` | The identifier of the shop every wand sells into. |
| `uses` | The uses of a new wand when `/sellwand give` is run without a number. `-1` for unlimited. |
| `containers` | The blocks the wand works on. `SHULKER_BOX` covers every dyed shulker box as well. |
| `wand.material` | The item the wand is made of. |
| `wand.display-name` | The name of the wand. |
| `wand.lore` | The lore of the wand. `%uses%` shows the uses left. |
| `wand.unlimited-label` | What `%uses%` shows on a wand that never runs out. |

A change to the look applies to new wands, and to an existing wand the next time it is used.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/sell-wands

---

# ⚙️ Wands

## Using a wand

Hold the wand in the main hand and right-click one of the listed containers. Everything in it that the shop buys is sold in one go and the player is told what they earned.

| Case | Result |
| ---- | ------ |
| Nothing in the container sells | No use is spent. |
| A region plugin blocks opening the container | The wand does nothing, so it cannot sell out of someone else's protected chest. |
| The container is not in the list | The click works as a normal right-click. |

The items pass through the player's inventory on their way to the shop, so a player with a full inventory cannot sell and is told so.

## Uses

Every right-click that sells something spends one use, and the uses left are shown in the wand's lore. A wand on its last use is gone once used. A wand with `-1` uses never runs out.

Wands are recognised by a hidden tag, not by their name or material, so renaming one in an anvil does not stop it working.

## Settings

> **Info:**
Everything below is set in addons/SellWands/config.yml. The add-on has no editor.

```yaml
shop: shop
uses: 50
containers:
  - CHEST
  - TRAPPED_CHEST
  - BARREL
  - SHULKER_BOX
wand:
  material: BLAZE_ROD
  display-name: '&6Sell Wand'
  lore:
    - '&7Right-click a container to sell'
    - '&7everything inside it.'
    - ''
    - '&fUses Left: &e%uses%'
  unlimited-label: '&aUnlimited'
```

| Option | What it does |
| ------ | ------------ |
| `shop` | The identifier of the shop every wand sells into. |
| `uses` | The uses of a new wand when `/sellwand give` is run without a number. `-1` for unlimited. |
| `containers` | The blocks the wand works on. `SHULKER_BOX` covers every dyed shulker box as well. |
| `wand.material` | The item the wand is made of. |
| `wand.display-name` | The name of the wand. |
| `wand.lore` | The lore of the wand. `%uses%` shows the uses left. |
| `wand.unlimited-label` | What `%uses%` shows on a wand that never runs out. |

A change to the look applies to new wands, and to an existing wand the next time it is used.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/sell-wands/wands

---

# 🛒 Shop Stands

## Information

The Shop Stands add-on adds a block that buys and sells one item from one of your shops. A floating display above it shows the item and its prices. Every click goes through the same checks as the shop menu, so currencies, stock, limits, requirements, availability and conditions all apply.

A player who cannot open the stand's shop cannot use the stand either.

## Installation

To install this add-on, drag and drop the jar file into the PhoenixShop/addons folder, then restart your server.

> **Warning:**
The add-on requires the Premium edition. On Lite it refuses to load and the console names the jar to remove.

## Placing a stand

Give yourself a stand with `/pshop stand give`, then place it like any block. The stand remembers the shop, category and item it was given for.

| Click | Default action |
| ----- | -------------- |
| Right-click | Buy one lot. |
| Shift + right-click | Buy up to a stack, as much as fits and the player can afford. |
| Left-click | Sell one lot. |
| Shift + left-click | Sell every matching item the player carries. |

When the item is removed from the shop, the display says it is unavailable and clicks are refused until the stand is removed.

## Protection

Only players with the break permission can break a stand. Breaking it deletes the stand, and outside creative mode drops a new stand item for the same shop item. Explosions, pistons, fire, endermen and hoppers cannot move, destroy or reach into a stand.

> **Info:**
A left-click on a stand sells, so a staff member in survival mode cannot mine it. Use `/pshop stand remove` while looking at it, or break it in creative mode.

## Settings

> **Info:**
Everything below is set in addons/ShopStands/config.yml. The add-on has no editor.

```yaml
material: BARREL
refresh-seconds: 30
click-cooldown: 250
clicks:
  right: BUY
  shift-right: BUY_STACK
  left: SELL
  shift-left: SELL_ALL
display:
  text-height: 1.75
  show-item: true
  item-height: 1.35
  item-scale: 0.5
```

| Option | What it does |
| ------ | ------------ |
| `material` | The block a stand is placed as. Anything that is not a block falls back to `BARREL`. Changing it does not touch stands already placed, but old stand items can no longer be placed. |
| `refresh-seconds` | How often every display is redrawn, so price and stock changes show up. |
| `click-cooldown` | Milliseconds a player has to wait between two clicks on a stand. `0` turns it off. |
| `clicks.*` | The action of each click. One of `BUY`, `BUY_STACK`, `SELL`, `SELL_STACK`, `SELL_ALL` or `NONE`. |
| `display.text-height` | How far above the stand's base the text floats. |
| `display.show-item` | Whether the item itself floats above the stand, below the text. |
| `display.item-height` | How far above the stand's base the item floats. |
| `display.item-scale` | The size of the floating item. `1` is the size of a block. |

The display text, the stand item's name and lore, and every message are in the translation file, under the `shopstands` section.

## Files

| File | What it holds |
| ---- | ------------- |
| `PhoenixShop/addons/ShopStands/config.yml` | The settings above. |
| Plugin database | Every placed stand. An old `stands/` folder is moved there on first start and renamed `stands.migrated`. |
| `PhoenixShop/addons/ShopStands/translations/shopstands.translations.<lang>.yml` | The add-on messages and display lines. |

## Placeholders

Available in the display lines.

| Placeholder | Shows |
| ----------- | ----- |
| `%item%` | The item's name. |
| `%shop%` | The shop's name. |
| `%category%` | The category's name. |
| `%buy_price%` | The price of one lot after its category sale, with the full price struck through beside it while a sale runs, or the unavailable text when the item cannot be bought. [Price modifiers](../sell-boosters/README.md#price-modifiers) are left out of the shared display, but a click still applies them. |
| `%sell_price%` | What one lot sells for, or the unavailable text when the item cannot be sold. |
| `%buy_amount%` | How many items one bought lot gives. |
| `%sell_amount%` | How many items one sold lot takes. |
| `%stock%` | The stock left, or the unlimited text. |

## Commands

| Command | Description |
| ------- | ----------- |
| `/pshop stand give <player> <shop> <category> <item> [amount]` | Gives an online player up to 64 stands for a shop item. |
| `/pshop stand remove` | Removes the stand you are looking at, block included. |
| `/pshop stand list` | Lists every stand with its shop item and position. A stand whose item no longer exists is marked as missing. |

## Permissions

| Permission | What it allows |
| ---------- | -------------- |
| `phoenixshop.command.stand` | Giving, removing, listing and placing stands. |
| `phoenixshop.stands.break` | Breaking a stand. |

`phoenixshop.admin` grants both. Using a stand needs no permission of its own.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/add-ons/shop-stands

---

# 🎑 Customize Menus

> **Info:**
Most of what is on this page can also be done in-game, without touching a file. See [In-Game Menu Editor](../features/in-game-menu-editor.md).

## Shop Menus

Every shop has its own set of menus, in menus/shops/\<shop> inside the plugin folder. They are created the first time the shop loads, so two shops can look completely different.

| File | Menu |
| --- | --- |
| main.yml | The categories of the shop, the first menu players see. |
| categories/\<category>.yml | The items of one category. There is one file per category. |
| buy.yml | Picking how many of an item to buy. |
| sell.yml | Picking how many of an item to sell. |
| bulk-buy.yml | Buying up to nine stacks in one click. |
| bulk-sell.yml | Selling up to nine stacks in one click. |
| sell-menu.yml | The menu of `/sell menu`, where items are dropped in to be sold. |
| confirm.yml | The confirm screen shown before a purchase goes through. |
| confirm-sell.yml | The confirm screen shown before Sell All goes through. |

The Premium search and preview menus are shared by every shop, so they sit on their own at menus/search.yml and menus/preview.yml. The chest shop menus are shared the same way: menus/chest-shops/list.yml, menus/chest-shops/find.yml, menus/chest-shops/market.yml, menus/chest-shops/notifications.yml, menus/chest-shops/trade.yml, menus/chest-shops/preview.yml and menus/chest-shops/remove-staff.yml.

The chest shop menus are laid out in game from **Editor > Chest Shops > Menus**, and the Premium search and preview menus from **Editor > Menus**, the same way a shop's own menus are from its editor.

Renaming a shop or a category renames its menu files, and deleting one deletes them. `/pshop reload` reads every menu file again.

## Menu Settings

Every menu starts with the same settings block: the title, the number of rows, how often the menu refreshes and the actions run when it opens.

```yaml
settings:
  type: SHOP
  title: '%shop%'
  rows: 4
  refresh:
    enabled: false
    rate: 20
  on-open-actions: []
```

Leave `type` as it is, it tells the plugin which menu the file belongs to. The `rate` is in ticks, and a refreshing menu redraws its placeholders on that interval. The buy and sell menus refresh by default, so the balance they show stays current.

Titles, names and lore accept color codes and MiniMessage tags.

## Slots

Slots are counted from 0, starting at the top left of the menu, so the first row is 0 to 8 and the second is 9 to 17. A `slot` takes a single slot (`'4'`), a range (`'0-8'`), or a comma separated mix of both (`'0, 8, 36-44'`).

## Items

The `items` section holds the decoration of the menu: glass borders, info items, anything that is not one of the plugin's own buttons. Add as many entries as you want, with any name.

```yaml
items:
  info:
    slot: '4'
    material: NETHER_STAR
    amount: 1
    custom-model-data: 0
    glow: true
    hide-attributes: true
    display-name: '&6&lPhoenix Shop'
    lore:
    - '&7Pick a category below to start.'
    actions:
    - '[SOUND] BLOCK_AMETHYST_BLOCK_CHIME; 1; 1.4'
    hide-tooltip: false
```

Two more options are available on any entry and are not in the example above:

* **item-model** - The item model identifier to use, on server versions that support it.
* **tooltip-style** - The tooltip style of the item, such as `minecraft:blue` or one from a resource pack.

> **Warning:**
Placeholders are not filled in on entries under `items`. They only work in the title and in the plugin's own buttons described below.

## Buttons

The plugin's own buttons, such as `close`, `back` or `confirm`, sit at the top level of the file rather than under `items`. They take `slot`, `material`, `amount`, `custom-model-data`, `display-name`, `lore` and `actions`. Their click does what the button is for, and its `actions` run on top of that.

A button cannot be deleted from the file, but it can be moved anywhere or restyled.

## Menu Actions

The `actions` of an item or button, and the `on-open-actions` of a menu, are written as `[TYPE] arguments`, with the arguments separated by `;`.

| Action | Arguments | Edition |
| --- | --- | --- |
| `[SOUND]` | `sound; volume; pitch` | Lite |
| `[TITLE]` | `title; subtitle; fade in; stay; fade out` | Lite |
| `[ACTION_BAR]` | `message` | Lite |
| `[CLOSE_INVENTORY]` | None | Lite |
| `[MESSAGE]` | `message` | Premium |
| `[COMMAND]` | `console` or `player`; `command` | Premium |
| `[GAMEMODE]` | `gamemode` | Premium |
| `[PARTICLE]` | `particle; count; spread x; spread y; spread z` | Premium |

## Main Menu

main.yml shows one tile per enabled category, in the order the categories are sorted. They fill the category slots in that order.

* `category-slots` - The slots the category tiles fill.
* `category` - The look of a category tile. It has no slot of its own, and its material is replaced by the category's icon.
* `previous-page` and `next-page` - Shown only when the shop has more categories than `category-slots` holds.
* `close` - Closes the menu.

> **Warning:**
A shop with more categories than slots and no `next-page` button hides the extra categories. The console warns about it when it happens.

| Placeholder | Where | Description |
| --- | --- | --- |
| %shop% | Everywhere | The display name of the shop, without colors. |
| %shop\_colored% | Everywhere | The display name of the shop. |
| %category% | `category` | The display name of the category, without colors. |
| %category\_colored% | `category` | The display name of the category. |
| %items% | `category` | How many items the category holds. |
| %items\_word% | `category` | The word item or items, to match %items%. |
| %category\_lore% | `category` | The category's [lore](../main-features/categories/edit-category.md#lore), or its icon item's own lore when none is set, one line each. A category without either drops the line. |
| %sale% | `category` | The [category sale](../main-features/categories/edit-category.md#sale) badge while the sale runs, empty otherwise. ⭐ |
| %sale_ends% | `category` | A line with the time left on the sale, counting down every second. Left out while no sale with an end is running. ⭐ |
| %page% | Page buttons | The page the button leads to. |
| %pages% | Page buttons | How many pages there are. |

## Category Menu

Each categories/\<category>.yml lists the items of one category, page by page.

* `pagination` - The `slots` the items fill, how they are aligned, the `fill-item` for empty item slots, and the `previous-item` and `next-item` page buttons.
* `item-lore` - The lines added under every item's own lore, see below.
* `back` - Goes back to the main menu.

```yaml
item-lore:
  buy:
  - '&7Buy: &c%buy_price%%sale%'
  sell:
  - '&7Sell: &a%sell_price%'
  stock:
  - '&7Stock: &f%stock%'
  hint: '&6%click%: &e%action%.'
```

The `buy` lines are added only when the item and its category can be bought from, the `sell` lines only when both can be sold to, and the `stock` lines only when the item has limited stock. The `hint` is repeated once per click in the `click-mappings` of config.yml, skipping clicks that do nothing and actions the item does not allow.

> **Warning:**
Category files created before the Premium category sale keep their old `buy` line. Add `%sale%` to it by hand for the badges to show, and `%sale%` to the `category` name in main.yml. The countdown needs `%sale_ends%` added to the `category` lore the same way.

| Placeholder | Where | Description |
| --- | --- | --- |
| %shop% | Everywhere | The display name of the shop, without colors. |
| %shop\_colored% | Everywhere | The display name of the shop. |
| %category% | Everywhere | The display name of the category, without colors. |
| %category\_colored% | Everywhere | The display name of the category. |
| %player% | Everywhere | The name of the player viewing the menu. |
| %item% | `item-lore` | The name of the item, without colors. |
| %item\_colored% | `item-lore` | The name of the item. |
| %buy\_price% | `item-lore` | The buy price of the item. |
| %sell\_price% | `item-lore` | The sell price of the item. |
| %buy\_price\_base%, %sell\_price\_base% | `item-lore` | The price before any [price modifier](../add-ons/sell-boosters/README.md#price-modifiers). ⭐ |
| %stock% | `item-lore` | The stock left of the item. |
| %sale% | `item-lore` | The [category sale](../main-features/categories/edit-category.md#sale) badge while the sale runs, empty otherwise. ⭐ |
| %click% | `hint` | The name of the click, such as Left-Click. |
| %action% | `hint` | What that click does, such as buy. |
| %page% | Page buttons | The page the button leads to. |

## Buy and Sell Menus

buy.yml and sell.yml open when a player picks an item, and let them choose the amount before confirming.

* `remove-64`, `remove-16`, `remove-1`, `add-1`, `add-16` and `add-64` - The step buttons. The `amount` of a step button is how far it moves the amount, so the names are only defaults: set `add-16` to an amount of 10 and it adds 10.
* `preview` - Shows the item itself, with the button's lore added under the item's own.
* `max` - Fill Inventory on the buy menu, Sell All on the sell menu. It buys as many as fit in the inventory and off-hand, or sells as many as the player carries, after the confirm screen. It needs `phoenixshop.buy.fill-inventory` or `phoenixshop.sell.all`, and without it the button shows `no-permission-material` and `no-permission-lore` instead.
* `confirm` - Buys or sells the chosen amount, then goes back to the category.
* `bulk` - Opens the bulk menu.
* `back` - Goes back to the category.

Steps are counted in lots, a lot being the item's own amount. On an item sold in 16s, a step of 1 adds 16 items. The amount never goes below one lot or above nine full stacks.

| Placeholder | Description |
| --- | --- |
| %amount% | How many items are chosen. |
| %lots% | How many lots are chosen. |
| %price% | The price of the chosen amount. |
| %unit\_price% | The price of one lot. |
| %price\_base%, %unit\_price\_base% | The price before any [price modifier](../add-ons/sell-boosters/README.md#price-modifiers). ⭐ |
| %max% | The most the player can buy or sell right now. |
| %max\_price% | The price of %max%. |
| %item% | The name of the item, without colors. |
| %item\_colored% | The name of the item. |
| %shop% | The display name of the shop, without colors. |
| %shop\_colored% | The display name of the shop. |
| %balance% | The player's balance in the item's currency. |
| %stock% | The stock left of the item, or Unlimited. |

## Bulk Menus

bulk-buy.yml and bulk-sell.yml offer whole stacks in one click.

* `option-slots` - The first slot offers one stack, the second two stacks, and so on up to nine. Slots past the ninth are left empty. An item that does not stack, such as armour or tools, is bought one at a time, so bulk buying offers only the first option.
* `option` - The look of each offer. Its material is replaced by the item, stacked to show how many stacks it is.
* `back` - Goes back to the buy or sell menu.

| Placeholder | Where | Description |
| --- | --- | --- |
| %item% | Everywhere | The name of the item, without colors. |
| %item\_colored% | Everywhere | The name of the item. |
| %shop% | Everywhere | The display name of the shop, without colors. |
| %shop\_colored% | Everywhere | The display name of the shop. |
| %stacks% | `option` | How many stacks the offer is. |
| %amount% | `option` | How many items the offer is. |
| %price% | `option` | The price of the offer. |
| %price\_base% | `option` | The price before any [price modifier](../add-ons/sell-boosters/README.md#price-modifiers). ⭐ |

## Confirm Menu

confirm.yml is the screen that asks before a purchase goes through: every Bulk Buy, every Fill Inventory, and any other purchase above [Confirm Above](settings-file.md). confirm-sell.yml asks the same way before Sell All, with the same buttons. Each shop has its own.

* `disable` - Set to `true` to never ask in this shop, Bulk Buy included.
* `decline` - Cancels and goes back to the menu the purchase came from. Closing the menu does the same.
* `accept` - Buys it.
* `item` - The item being bought. Its material is replaced by the item, stacked to the amount bought up to one stack.

| Placeholder | Where | Description |
| --- | --- | --- |
| %amount% | Everywhere | How many items are being bought. |
| %item% | Everywhere | The name of the item. |
| %price% | Everywhere | The total price. |

## Sell Menu

sell-menu.yml is the menu of `/sell menu`. Players drop items into it, and everything a shop buys is sold, while the rest is given back. It is read from the first shop in the sell shop list that the player can open.

* `drop-slots` - The slots players can drop items into. Keep decoration and buttons out of them.
* `confirm` - Sells the contents and closes the menu.

| Placeholder | Where | Description |
| --- | --- | --- |
| %shop% | Everywhere | The display name of the shop, without colors. |
| %shop\_colored% | Everywhere | The display name of the shop. |
| %total% | `confirm` | What the dropped items are worth. |
| %close\_hint% | `confirm` | A line saying closing the menu also sells, shown only when it does. |

## Search Menu ⭐

> **Info:**
The search menu is available in the Premium plan of Phoenix Shop.

menus/search.yml is the menu of `/pshop search`. It is paginated like a category menu.

* `terms` - Left-click types a search, right-click clears it.
* `filter` - Click with an item on the cursor to search for that item, or with an empty cursor to clear it. See [Search by Item](../features/search.md#search-by-item).
* `sort` - Changes the order of the results.
* `close` - Closes the menu.
* `result-lore` - The `buy`, `sell` and `footer` lines added under every result.

| Placeholder | Where | Description |
| --- | --- | --- |
| %player% | Everywhere | The name of the player viewing the menu. |
| %terms% | `terms`, `sort` | What is being searched for. |
| %order% | `terms`, `sort` | The current order. |
| %filter% | `filter` | The name of the item searched for, or none. |
| %item% | `result-lore` | The name of the result. |
| %shop% | `result-lore` | The shop the result is in. |
| %category% | `result-lore` | The category the result is in. |
| %buy\_price% | `result-lore` | The buy price of the result. |
| %sell\_price% | `result-lore` | The sell price of the result. |
| %buy\_price\_base%, %sell\_price\_base% | `result-lore` | The price before any [price modifier](../add-ons/sell-boosters/README.md#price-modifiers). |

## Preview Menu ⭐

> **Info:**
The preview menu is available in the Premium plan of Phoenix Shop.

menus/preview.yml opens with the `PREVIEW` [click action](main-configuration.md#click-mappings). Its list shows every purchase item, paginated like a category menu.

* `info` - The shop item. When the item runs purchase commands, the `preview.commands` translation lines are added under it.
* `back` - Goes back to the category.
* `empty` - Shown when the item gives no items and only runs commands.
* `item-lore` - The lines added under every purchase item.

| Placeholder | Where | Description |
| --- | --- | --- |
| %player% | Everywhere | The name of the player viewing the menu. |
| %item%, %item\_colored% | Everywhere | The name of the shop item, without and with colors. |
| %shop%, %shop\_colored% | Everywhere | The display name of the shop, without and with colors. |
| %price% | Everywhere | The price of one purchase for the player. |
| %count% | Everywhere | How many items one purchase gives. |
| %commands% | Everywhere | How many purchase commands the item runs. |
| %amount% | `item-lore` | How many of that item one purchase gives. |

### Chest Shop Item Preview

menus/chest-shops/preview.yml opens when a player clicks **\[Item Preview]** in a chest shop's info panel. It shows the shop's item with its full tooltip, framed with gray glass and titled **Item Preview**.

* `item` - The chest shop's item. Its own name and lore are kept; a `display-name` replaces the name and `lore` lines are added under it.

| Placeholder | Description |
| --- | --- |
| %player% | The name of the player viewing the menu. |
| %item%, %item\_colored% | The name of the chest shop's item, without and with colors. |
| %owner% | The owner of the chest shop. |

### Chest Shop Trade

menus/chest-shops/trade.yml opens when a player asks for an amount on a Buy & Sell chest shop, or trades with any shop through [Remote Trading](../main-features/player-shops/settings.md#remote-trading). Clicking Buy or Sell asks how many.

* `close` - Closes the menu.
* `item` - The chest shop's item. Its own name and lore are kept; a `display-name` replaces the name and `lore` lines are added under it.
* `buy`, `sell` - Ask how many to buy or sell.
* `buy-unavailable`, `sell-unavailable` - Shown in their place when the shop does not sell or buy, or has no price set for that side.
* `items` - The black glass bar on the bottom row. Remove it for a menu without the bar.

| Placeholder | Where | Description |
| --- | --- | --- |
| %player% | Everywhere | The name of the player viewing the menu. |
| %item%, %item\_colored% | Everywhere | The name of the chest shop's item, without and with colors. |
| %owner% | Everywhere | The owner of the chest shop. |
| %amount% | Everywhere | How many items one trade moves. |
| %price% | `buy`, `sell` | The shop's buy or sell price for that amount. |

### Remove Staff

menus/chest-shops/remove-staff.yml opens when a chest shop owner clicks a player in their shop's [Staff](../main-features/player-shops/edit-player-shop.md#staff) menu. Closing it keeps the player as staff. Set `disable` to `true` to remove staff on the click, without asking.

* `decline` - Keeps the player as staff.
* `accept` - Removes the player from the staff.
* `item` - The player's head.

| Placeholder | Description |
| --- | --- |
| %player% | The staff member being removed. |

### Chest Shop Notifications

menus/chest-shops/notifications.yml opens with [/chestshop notifications](../main-features/player-shops/trading.md#owner-notices).

* `close` - Closes the menu.
* `buy`, `sell`, `teleport`, `out-of-stock`, `chest-full` - Turn each kind of notice on or off for the player.
* `choice`, `choice-selected`, `enabled`, `disabled` - How the On and Off choices are listed where a button's lore has a `%choices%` line.

### Chest Shop List and Find

menus/chest-shops/list.yml is the menu of [/chestshop list](../main-features/player-shops/README.md#shop-list) and menus/chest-shops/find.yml the one of [/chestshop find](../main-features/player-shops/README.md#find-a-shop). Both files have the same options, so the two menus can look alike or different. The `pagination` section places the shops and the page arrows.

<figure><img src="../.gitbook/assets/chest-shop-list/chest-shop-list.png" alt="" width="563"><figcaption><p>Chest Shops (Entry)</p></figcaption></figure>

<figure><img src="../.gitbook/assets/chest-shop-list/filter.png" alt="" width="563"><figcaption><p>Chest Shops (Filter)</p></figcaption></figure>

* `close` - Closes the menu.
* `filter` - Switches between all shops, the ones selling and the ones buying.
* `order` - Switches between the default order and price low to high or high to low.
* `choice`, `choice-selected` - How each choice is listed on those two buttons, where their lore has a `%choices%` line. The current one uses `choice-selected`.
* `empty` - Shown in place of the shops when none match the filter.
* `entry.name`, `entry.named` - The name of a shop's entry, the second one for a shop with a name.
* `entry.lore` - The lines under the item's own enchantments and lore.
* `entry.stock`, `entry.room` - Added under them: how many items a selling shop holds (`%stock%`) and how many more a buying shop has room for (`%room%`).
* `entry.unknown`, `entry.unlimited` - Shown in place of the number when it is not known yet, and on admin shops.
* `entry.teleport-lore`, `entry.trade-lore` - Added only for a player who can teleport to shops or trade with them from afar.
* `prices.buy`, `prices.sell`, `prices.both` - What `%prices%` shows for a Buy, Sell or Buy & Sell shop.

The names of the filter and order choices are in the translation file.

| Placeholder | Where | Description |
| --- | --- | --- |
| %player% | Everywhere | The name of the player viewing the menu. |
| %item% | Title of `chest-shops/find.yml` | What was searched for. |
| %item%, %name%, %owner%, %amount%, %prices% | Entries | The shop's item, its name, its owner, how many trade per click and its prices. |
| %price% | `prices.buy`, `prices.sell` | The price of the side shown. |
| %buy%, %sell% | `prices.both` | The two prices of a Buy & Sell shop. |
| %currency% | `stats` | The currency the overview is counted in. |
| %sellers%, %lowest-buy%, %average-buy% | `stats` | How many shops sell the item, and the lowest and average price for one. |
| %buyers%, %highest-sell%, %average-sell% | `stats` | How many shops buy the item, and the best and average offer for one. |
| %trades%, %average-traded% | `stats` | Trades in the last 30 days and their average price for one. |

* `stats` - The [Price Overview](../main-features/player-shops/README.md#find-a-shop), only drawn in the find menu.
* `stats-none` - Shown in place of a price no shop has.

### Chest Shop Market

menus/chest-shops/market.yml is the menu of [/chestshop market](../main-features/player-shops/README.md#market). The `pagination` section places the items and the page arrows.

* `close` - Closes the menu.
* `order` - Switches between most shops, name and cheapest first.
* `choice`, `choice-selected` - How each order is listed where the button's lore has a `%choices%` line.
* `empty` - Shown when no chest shop trades an item.
* `entry.name`, `entry.lore` - The name and lines of an item's entry.
* `entry.seller`, `entry.no-seller` - What `%seller%` shows, with or without a shop selling the item.
* `entry.buyer`, `entry.no-buyer` - What `%buyer%` shows, with or without a shop buying it.

| Placeholder | Where | Description |
| --- | --- | --- |
| %player% | Everywhere | The name of the player viewing the menu. |
| %item%, %sellers%, %buyers% | Entries | The item, and how many shops sell and buy it. |
| %seller%, %buyer% | `entry.lore` | The cheapest seller and the best buyer lines. |
| %price%, %owner% | `entry.seller`, `entry.buyer` | The price for one item and the shop's owner. |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/customize-menus

---

# 🗂️ File Structure

## Overview

Everything the plugin writes lives in plugins/PhoenixShop.

```
plugins/PhoenixShop/
├── shops/
│   ├── shop.yml
│   └── shop/
│       ├── blocks.yml
│       └── valuables.yml
├── menus/
├── translations/
├── addons/
├── exports/
├── backups/
├── layout-sessions/
├── data/
│   └── database.db
├── config.yml
├── settings.yml
├── chest-shops.yml
├── auction-house.yml
├── discord.yml
└── pricing.yml
```

## Folders

| Folder              | Contents                                                                                           |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| **shops**           | One file per shop, plus a folder of the same name holding one file per category. See [Shop Configuration File](shop-configuration-file.md). |
| **menus**           | The menu layouts: one folder per shop under `shops`, the Auction House menus under `auction-house`, and the shared menus. See [Customize Menus](customize-menus.md). |
| **translations**    | The language file. See [Languages & Translations](languages.md).                                   |
| **addons**          | Add-on jars, and a folder per add-on with its own settings. Drop a new add-on here and restart.    |
| **admin\_signs**    | Sign shops from an older version. They are moved into the database on first start and the folder is renamed **admin\_signs.migrated**. |
| **exports** ⭐      | Purchase history exported with `/pshop history export`.                                            |
| **backups**         | A copy of a file taken before the plugin rewrote it. See the note below.                          |
| **layout-sessions** | The inventory of an admin editing a menu layout, kept so it is given back after a crash. Never edit this by hand. |
| **data**            | The SQLite database, `database.db`, when SQLite is used. It holds every player shop, sign shop and shop stand. While the server runs, SQLite keeps two more files next to it, `database.db-wal` and `database.db-shm`, with the latest changes. Older versions kept it in the main folder; it is moved here on the first start. |

## Files

| File                  | Contents                                                                                |
| --------------------- | --------------------------------------------------------------------------------------- |
| **config.yml**        | The main settings and the database connection. See [Main Configuration](main-configuration.md). |
| **settings.yml**      | Transactions, menus, locked categories, the IP limit and sign shops. See [Settings File](settings-file.md). |
| **chest-shops.yml**   | The chest shop settings. See [Player Shops Settings](../main-features/player-shops/settings.md). |
| **auction-house.yml** | The Auction House settings. See [Auction House](../features/auction-house.md). |
| **discord.yml** ⭐    | The Discord webhooks.                                                                   |
| **pricing.yml**       | The last 10 price generator runs, so they can be undone.                                |

> **Info:**
When a file is missing settings, the plugin rewrites it and keeps what you had in backups, under the same path. A shop or category file that is not valid YAML is never rewritten: it is skipped, reported in the console, and left exactly as it is until you fix it and run /pshop reload.

## What Lives in the Database

Transactions, remaining stock, per-player purchase limits and restock timers are **not** in these files, and neither are restock alert choices ⭐. They are stored in the database configured in `config.yml`, which is SQLite (`data/database.db`) by default and MySQL or MariaDB ⭐ if you set it up.

## Moving to Another Server

To carry your setup across:

* **Configuration** - copy `shops/`, `menus/`, `translations/`, `config.yml`, `settings.yml` and the add-on folders inside `addons/`.
* **Sign and chest shops** - sign shops, shop stands and player shops are in the database, so they come across with it, but only if the worlds come across too.
* **Transactions and stock** - point the new server at the same MySQL database, or stop the server and copy the `data` folder across.

## What to Back Up

The whole plugins/PhoenixShop folder, plus your database if you use MySQL or MariaDB. The editor writes changes to the files as you make them, so those can be backed up while the server runs. For the SQLite database, stop the server first, or copy all three files in `data` together: `database.db` alone can miss the latest changes.

## Reporting a Problem

Turning on `debug` in `config.yml` adds verbose console logging, which is useful to attach when you report an issue to us.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/file-structure

---

# 🛠️ GeyserMC (Bedrock)

> **Info:**
These options are in the bedrock section of config.yml. They have no editor option.

## Overview

Bedrock players joining through Geyser can use the shop as native Bedrock forms instead of chest menus: a list of buttons for the categories and the items, a slider to pick the amount, and a toggle list to sell from the inventory. Forms need Floodgate or Geyser to be installed on the same server as the plugin. Without either, everyone gets the chest menus.

**Please note:** This guide will not cover the installation process of Geyser itself. Refer to the Geyser wiki for comprehensive installation instructions: [Geyser Wiki Setup](https://wiki.geysermc.org/geyser/setup/)

```yaml
bedrock:
  forms: true
  input-modes: []
  allow-opt-out: true
  resize-chest-menus: true
  after-transaction: CATEGORY
  confirm-above: 0
  custom-amount: true
  show-balance: true
  sell-form: true
  icons:
    enabled: true
    fallback-url: ""
    head-url: "https://mc-heads.net/head/%texture%"
```

## How the Forms Work

| Menu | Bedrock form |
| --- | --- |
| Main menu | A button per enabled category, showing how many items it holds. |
| Category menu | A button per item, showing its buy and sell price. An item that can be both bought and sold asks which one first. |
| Buy and sell menus | A slider from one lot up to as many as fit in the inventory when buying, or as many as the player carries when selling, capped at nine stacks. Items that do not stack are bought one at a time. |
| Bulk menus | Replaced by the slider form, which already covers up to nine stacks. |
| Sell menu | A toggle per kind of item in the inventory that a shop buys, all on by default. |

Buttons use the display names of the shop, the categories and the items, with colors kept and hex colors removed, since forms cannot show them. The text around them, such as the balance line, the back button and the confirmation, comes from the bedrock section of the translations file.

The actions of the category tile and the open and close actions of a category still run. Everything else about the chest menu layout does not apply to forms.

If a form cannot be sent, the player gets the chest menu instead and the console says so.

## Forms

Turns Bedrock forms on or off for the whole server. When off, Bedrock players get the chest menus like everyone else.

## Input Modes

Limits forms to Bedrock players on certain devices, by their input mode: `TOUCH`, `CONTROLLER`, `KEYBOARD_MOUSE` or `VR`. Players on any other input get chest menus. Leave the list empty to give forms to every Bedrock player.

```yaml
bedrock:
  input-modes:
  - TOUCH
  - CONTROLLER
```

## Allow Opt Out

Lets Bedrock players choose chest menus for themselves. The main shop form gets a button to switch to chest menus, and `/pshop forms` switches between the two. The choice is remembered per player. When this is off, every Bedrock player gets forms and the command is refused.

## Resize Chest Menus

Bedrock only draws chest menus of 3 or 6 rows cleanly. With this on, a menu of 1 or 2 rows is opened with 3 rows and a menu of 4 or 5 rows with 6, for Bedrock players who get chest menus. Java players always see the rows the menu is set to.

## After Transaction

Where a Bedrock player goes after a purchase or sale on the slider form goes through.

| Value | Goes to |
| --- | --- |
| `CATEGORY` | Back to the category, to pick another item. |
| `TRANSACTION` | The same slider form again, to buy or sell more of the item. |
| `CLOSE` | Nowhere, the form closes. |

A refused transaction always opens the slider form again.

## Confirm Above

A total price from which a purchase or sale asks for confirmation before going through. Anything cheaper goes through straight away. Set it to 0 to never ask.

## Custom Amount

Adds a text field under the slider where the player can type an exact amount. A typed amount wins over the slider, and shorthands such as `1.5k` are accepted. An amount that is not a number reopens the form with a message.

## Show Balance

Shows the player's balance at the top of the shop, category and slider forms, in the currency that applies there.

## Sell Form

Replaces the `/sell menu` chest, where items are dragged in, with a form listing every item in the inventory that a shop buys. The player turns off what they want to keep and submits. When off, Bedrock players get the chest version.

## Icons

Adds an icon to form buttons.

* **enabled** - Turns icons on or off.
* **fallback-url** - An image URL for materials the built-in icon table does not know. `%material%` is replaced by the material name in lower case. Leave it empty for no icon.
* **head-url** - An image URL for player heads. `%texture%` is replaced by the head's texture id, or the owner's name when it has no texture. Leave it empty for no head icons.

Vanilla items use the Bedrock texture of the same item, which every Bedrock client already has. Custom items, meaning items from another plugin, items with custom model data and items with an item model, get no icon, since their texture only exists in a resource pack. Player heads always use the head URL.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/geysermc-bedrock

---

# 🌍 Languages & Translations

## Translations

Every line the plugin can print lives in one file:

```
PhoenixShop/translations/translations.en.yml
```

Messages to players, command replies, the menus and the whole in-game editor are all in there. Edit it and run /pshop reload to apply the new text. Player shop signs show it after their next trade or restock.

## Language

The plugin ships with English only, and there is no language option. To run it in another language, translate the file yourself.

## Translating the plugin

Everything sits under `en` at the top of the file, and the value is either a line or a list of lines. Translate the right-hand side and leave the keys and the placeholders alone.

```yaml
en:
  cannot-buy: "%prefix%&f%item% &cis not for sale here."
  shop-currency-missing:
    - "%prefix%&cThe shop &f%shop%&c cannot open: it is priced in &f%currency%&c."
    - "&7Install &f%plugin%&7 and run &f/pshop reload&7."
```

Anything wrapped in `%` is filled in by the plugin, so `%item%`, `%shop%` and `%price%` have to survive the translation to keep working. Colour codes can be moved around freely.

## The Prefix

`%prefix%` at the start of a message is replaced with the `plugin-prefix` line, so the prefix of every message is changed in one place.

```yaml
en:
  plugin-prefix: "&#7852A9&lPhoenixShop &8» &7"
```

Remove `%prefix%` from a message to send that one without it. Set `plugin-prefix` to `''` to drop it everywhere.

## Updating the plugin

New keys reach your file on their own. On start, any key the plugin ships that your file does not have is written into it with its English default, and the console prints `Missing value for key "..."` for each one.

Keys you already have are never touched. A message whose default wording changed in an update keeps your old text, so compare with the file inside the new jar if you want the new wording.

> **Info:**
Keep a copy of your translated file before updating the plugin. New keys are added to it automatically, but it is the file your work lives in.

## The editor is translated too

Everything under the `editor` keys is the text of the in-game editor, the name and description of every option. Translating those is optional, and skipping them leaves the editor in English while your players see your language.

## Rich Text (MiniMessage)

Phoenix Shop understands [MiniMessage](https://docs.advntr.dev/minimessage/format.html) tags, like `<red>`, `<bold>` or `<gradient:#ff5555:#5555ff>`, on top of the classic `&` colour codes and `&#RRGGBB` hex colours.

### Format

| Example                                               | Result                                 |
| ----------------------------------------------------- | -------------------------------------- |
| `&aHello`                                             | Green text                             |
| `&#ff8800Hello`                                       | Any hex colour                         |
| `<#ff8800>Hello`                                      | Any hex colour, MiniMessage style      |
| `<gradient:#FF9A00:#E52D27>Phoenix Shop</gradient>`   | Text fading from one colour to another |
| `<bold><underlined>Warning`                           | Bold and underlined                    |
| `<rainbow>Rare!</rainbow>`                            | Each letter a different colour         |

A closing tag is optional. `<red>Hello` colours the rest of the line, while `<red>Hello</red> there` colours only the first word.

### Where it works

| Place                              | Notes                                               |
| ---------------------------------- | --------------------------------------------------- |
| Shop and category names            | The shop's display name and the category's title    |
| Item names and lore                | Including purchase items                            |
| Menu titles, item names and lore   | Everything in the `menus` files                     |
| Sign shops                         | The lines of chest shops and server-owned sign shops |
| Message, title and action bar actions ⭐ | Actions run by requirements and categories    |

In these places `&` codes and tags can be mixed freely in the same line.

### Where it doesn't work

Messages in the translation file, such as the bought and sold messages, only understand `&` codes and `&#RRGGBB` hex. A tag in one of them is shown to the player exactly as you typed it.

Hover text and clickable links are not supported anywhere, since every text is turned into plain coloured text before it is shown.

### Usage notes

* A tag the server does not recognise is left in the text as written rather than being dropped, which is what keeps resource pack glyph tags working.
* Bedrock forms drop hex colours and gradients, and keep the standard `&` colours.

> **Warning:**
MiniMessage needs [Paper](https://papermc.io/) or a fork of it. On plain Spigot the tags are printed exactly as you typed them, so stay on `&` codes there.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/languages

---

# 📁 Main Configuration

> **Info:**
Changes made by hand in config.yml apply with /pshop reload, except the Internal Pool Size and the Database settings, which need a restart. The console names any of those that changed. Options changed from the editor are saved straight away.

## General Configuration

* **Internal Pool Size** - The number of threads the plugin keeps for its own background work, such as database reads. The default of `10` suits almost every server.
* **Debug** - Adds verbose logging to the console, useful when reporting an issue.
* **Notify If New Version** - Whether the console and players with `phoenixshop.admin` are told when a newer build is out, and admins are offered the changelog after an update.
* **Send Server Statistics** - Lite only. Sends the server version, software, join domains and player count to our servers so the server shows on the website. See [Server Statistics](../plugin-information/licensing.md#server-statistics).
* **Error Reports** - Sends errors thrown by the plugin's own code to us so we can fix them without asking for your logs: the error and its stack trace, the plugin, server and Java versions, and your plugin list. Player names, UUIDs, IP addresses and your server's folder path are removed first, and each kind of error is sent once with a count. On by default on Premium and off on Lite.

```yaml
performance:
  internal-pool-size: 10
debug: false
notify-if-new-version: true
send-server-statistics: true
error-reports: true
```

Update notices, and on Lite the Premium reminder admins see on join, can also be turned off from **Editor > Settings > General**.

## Database

Transactions, stock counts and restock timers are stored in the database. The available types are sqlite, mysql and mariadb.

```yaml
database:
  type: sqlite
  address: localhost
  name: phoenixshop_db
  port: 3306
  username: phoenixuser
  password: phoenixpassword
  table-prefix: ps
  jdbc-url-options: createDatabaseIfNotExist=true&useSSL=false&characterEncoding=UTF-8
```

`jdbc-url-options` is added to the MySQL or MariaDB connection URL. Change it when your database host needs other options, such as `allowPublicKeyRetrieval=true` for a MySQL 8 user that has no SSL. It takes effect after a restart.

> **Warning:**
⭐ MySQL and MariaDB are Premium only. The Lite version uses SQLite whatever the type says, prints a warning in the console and leaves your settings in the file untouched.

## History

How many days a transaction is kept in the database before it is deleted. `0` or less keeps every transaction forever.

```yaml
history:
  keep-days: 7
```

It can also be set from **Editor > Settings > General**.

The history itself can be browsed with /pshop history, and exported with /pshop history export ⭐.

## Undo ⭐

Lets a player reverse their last transaction with /pshop undo, as long as it happened within the window.

```yaml
undo:
  enabled: true
  window-seconds: 30
```

## Player Shops

Chest shops that players build themselves with a sign. Their settings are in chest-shops.yml, not config.yml; the full list is on [Player Shops Settings](../main-features/player-shops/settings.md).

| Option             | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **enabled**        | Turns chest shops on or off. While off, nobody can trade on one, the owner included, and none can be made. On Lite, admin shops ignore it. |
| **creation-cost**  | Charged once, in money (Vault), when the shop is made. `0` makes it free.                            |
| **max-per-player** | How many chest shops one player can own. `0` removes the limit.                                      |
| **sign-material**  | The sign placed on new shops, such as `SPRUCE_SIGN` or `SPRUCE_WALL_SIGN`. Any other material falls back to oak, and hanging signs are not supported. |
| **short-prices** | Shows prices of 1,000 and up as `$250k`, `$1.5m` and so on in chat, menus and holograms. Signs always do. |
| **click-confirm** | `enabled` makes the first sign click on a shop ask to click again; `minutes` is how long a confirmed shop trades without asking. |
| **protected-names** | Names only real plugin items may carry; `*` matches anything. Renamed items with these names cannot be sold. |
| **trade-click** ⭐ | `INSTANT` (default) trades the shop's fixed amount on every click, `PROMPT` asks the customer how many to trade. See [Trade Click](../main-features/player-shops/settings.md#trade-click). |
| **teleport** ⭐    | Lets `/chestshop list` and `/chestshop find` teleport to a shop, for players with `phoenixshop.sign.teleport`. |
| **remote-trading** ⭐ | Lets players with `phoenixshop.sign.remote` trade with a shop from `/chestshop list` and `/chestshop find` without walking to it. See [Remote Trading](../main-features/player-shops/settings.md#remote-trading). |

```yaml
enabled: false
creation-cost: 0
max-per-player: 0
sign-material: OAK_SIGN
protected-names: []
short-prices: true
click-confirm:
  enabled: true
  minutes: 5
trade-click: INSTANT
teleport: true
remote-trading: false
```

## Commands

Every command of the plugin except `/phoenixshop`, and of its add-ons: `chest-shop`, `sell`, `auction-house`, and `autosell`, `rotating-shop`, `sell-boosters` and `sell-wands` while that add-on is installed. Each one can be renamed, given other names and have its subcommands renamed, for example into your own language. They can also be changed in game from **Editor > Settings > Commands**, where changes apply right away.

| Option | Description |
| --- | --- |
| **enabled** | Registers the command. Turning it off removes it. |
| **alternative** | The command's name. |
| **aliases** | Other names for the same command. |
| **subcommands** | A new name per subcommand, such as `collect: recoger`. Messages that mention the subcommand use the new name, and the old name keeps working. Permissions do not change. |

```yaml
commands:
  chest-shop:
    enabled: true
    alternative: chestshop
    aliases:
      - cs
    subcommands: {}
  auction-house:
    enabled: true
    alternative: ah
    aliases:
      - auction
      - auctionhouse
    subcommands:
      collect: recoger
```

Changes made in the file apply with /pshop reload. If another plugin already owns one of these names, PhoenixShop takes it over, and that plugin's command stays reachable with its prefix, such as `/worldedit:cs`.

## Settings File

Transactions, menus, locked categories, the IP limit and sign shops are set in settings.yml. See [Settings File](settings-file.md).

## Click Mappings

What each click on an item in a category does. The key is the click and the value is the action.

```yaml
click-mappings:
  LEFT: BUY
  RIGHT: SELL
  SHIFT_LEFT: BUY
  SHIFT_RIGHT: SELL_ALL
```

| Action     | Description                                                     |
| ---------- | --------------------------------------------------------------- |
| BUY        | Opens the buy menu, where the player picks the amount.          |
| SELL       | Opens the sell menu, where the player picks the amount.         |
| BUY\_ONE   | Buys one purchase straight away.                                |
| SELL\_ONE  | Sells one purchase straight away.                               |
| BUY\_STACK | Buys as many purchases as fit in one stack, straight away.      |
| SELL\_ALL  | Sells every matching item the player carries, straight away. Needs `phoenixshop.sell.all`. |
| PREVIEW ⭐ | Opens the [preview](../features/preview.md#preview) of what one purchase gives. Needs `phoenixshop.preview`. |
| NONE       | Does nothing.                                                   |

A click left out of the list does nothing. The keys are Bukkit click types, so `DROP` (Q) and `CONTROL_DROP` (Ctrl + Q) can be mapped too. `MIDDLE` is left out, as the game only sends a middle-click in creative mode. An action name that does not exist is reported in the console and skipped.

`PREVIEW` is not mapped by default. Swap it in for a click to use it, such as `SHIFT_RIGHT: PREVIEW`. On Lite it does nothing and is left out of the item's hint lines.

## Search ⭐

Shops left out of [/pshop search](../features/search.md#search), by identifier.

```yaml
search:
  excluded-shops: []
```

## Restock and Sale Alerts ⭐

How players are told that an item is back or on sale, see [Restock & Sale Alerts](../features/restock-and-sale-alerts.md).

| Option | Description |
| --- | --- |
| **enabled** | Turns restock and sale alerts on or off for everyone. |
| **chat** | Sends the alert in chat. |
| **title** | Shows the alert as a title and subtitle. |
| **sound** | Played with the alert, as `SOUND, volume, pitch`. Empty plays no sound. |

```yaml
alerts:
  enabled: true
  chat: true
  title: true
  sound: 'BLOCK_NOTE_BLOCK_PLING, 1, 1'
```

## Sell

The settings of /sell and the sell menu.

<figure><img src="../.gitbook/assets/sell-command/sell-command.png" alt="" width="563"><figcaption><p>Settings (Sell Command)</p></figcaption></figure>

| Option               | Description                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------- |
| **shops-whitelisted** | The shops `/sell` sells to. A shop the player cannot open is skipped.                        |
| **sell-on-close**    | Closing the sell menu sells what is in it. When off, the items are given back unless the player confirms. |
| **shulker-boxes**    | `/sell inventory`, `/sell hand` and the sell menu also sell what is inside shulker boxes. See [Shulker Boxes](../main-features/selling/README.md#shulker-boxes). |
| **sounds.sold**      | Played after a sale, as `SOUND, volume, pitch`.                                               |
| **sounds.deny**      | Played when nothing could be sold.                                                            |
| **sold.message**     | Sends the sold message in chat.                                                               |
| **sold.title**       | Shows the sold title, with its fade-in, stay and fade-out in ticks.                           |

```yaml
sell:
  shops-whitelisted:
    - shop
  sell-on-close: true
  shulker-boxes: true
  sounds:
    sold: 'ENTITY_PLAYER_LEVELUP, 1, 1'
    deny: 'BLOCK_NOTE_BLOCK_BASS, 1, 1'
  sold:
    message: true
    title:
      enabled: true
      fade-in: 5
      stay: 40
      fade-out: 10
```

Most of these can also be changed from **Editor > Settings > Sell**.

## Bedrock

How Bedrock players using Geyser or Floodgate see the shops. Every option is explained on [GeyserMC / Bedrock](geysermc-bedrock.md).

```yaml
bedrock:
  forms: true
  input-modes: []
  allow-opt-out: true
  resize-chest-menus: true
  after-transaction: CATEGORY
  confirm-above: 0
  custom-amount: true
  show-balance: true
  sell-form: true
  icons:
    enabled: true
    fallback-url: ""
    head-url: "https://mc-heads.net/head/%texture%"
```

## Currency Symbols

The symbol shown next to each price in the editor's item list. The key is the currency's identifier, and a PlaceholderAPI placeholder can be used as the symbol. A currency with no entry shows its own name.

```yaml
currency-symbols:
  money: "$"
  points: "Points"
  experience: "XP"
  levels: "Levels"
  votepoints: "Vote Points"
```

> **Info:**
There is no list of currencies in this file. The currency of a shop, category or item is picked in the editor and saved in that shop's own file. See [Shop Configuration File](shop-configuration-file.md#currency).

## Messages & Translations

Every message the plugin sends lives in the translation file rather than in config.yml. Editing the wording and silencing a message are on [Languages & Translations](languages.md).

## MiniMessage

On top of the usual `&` colour codes, shop names, item names, lore and menus accept MiniMessage tags for gradients and hex colours. See [Rich Text (MiniMessage)](languages.md#rich-text-minimessage).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/main-configuration

---

# 🎨 Rich Text (MiniMessage)

## Information

Phoenix Shop understands [MiniMessage](https://docs.advntr.dev/minimessage/format.html) tags, like `<red>`, `<bold>` or `<gradient:#ff5555:#5555ff>`, on top of the classic `&` colour codes and `&#RRGGBB` hex colours.

## Format

| Example                                               | Result                                 |
| ----------------------------------------------------- | -------------------------------------- |
| `&aHello`                                             | Green text                             |
| `&#ff8800Hello`                                       | Any hex colour                         |
| `<#ff8800>Hello`                                      | Any hex colour, MiniMessage style      |
| `<gradient:#FF9A00:#E52D27>Phoenix Shop</gradient>`   | Text fading from one colour to another |
| `<bold><underlined>Warning`                           | Bold and underlined                    |
| `<rainbow>Rare!</rainbow>`                            | Each letter a different colour         |

A closing tag is optional. `<red>Hello` colours the rest of the line, while `<red>Hello</red> there` colours only the first word.

## Where it works

| Place                              | Notes                                               |
| ---------------------------------- | --------------------------------------------------- |
| Shop and category names            | The shop's display name and the category's title    |
| Item names and lore                | Including purchase items                            |
| Menu titles, item names and lore   | Everything in the `menus` files                     |
| Sign shops                         | The lines of chest shops and server-owned sign shops |
| Message, title and action bar actions ⭐ | Actions run by requirements and categories    |

In these places `&` codes and tags can be mixed freely in the same line.

## Where it doesn't work

Messages in the translation file, such as the bought and sold messages, only understand `&` codes and `&#RRGGBB` hex. A tag in one of them is shown to the player exactly as you typed it.

Hover text and clickable links are not supported anywhere, since every text is turned into plain coloured text before it is shown.

## Usage notes

* A tag the server does not recognise is left in the text as written rather than being dropped, which is what keeps resource pack glyph tags working.
* Bedrock forms drop hex colours and gradients, and keep the standard `&` colours.

> **Warning:**
MiniMessage needs [Paper](https://papermc.io/) or a fork of it. On plain Spigot the tags are printed exactly as you typed them, so stay on `&` codes there.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/rich-text

---

# ⚙️ Settings File

> **Info:**
These options are in settings.yml, next to config.yml. Changes made by hand apply with /pshop reload. Options changed from the editor are saved straight away.

## Sign Shops

Server-owned sign shops placed by the staff. The [sign text](../main-features/admin-signs/README.md#sign-text) is in the same section. The sounds, the click cooldown and the sign text can also be changed from **Editor > Sign Shops > Settings**.

<figure><img src="../.gitbook/assets/sign-shop-settings/sign-shop-settings.png" alt="" width="563"><figcaption><p>Settings (Sign Shops)</p></figcaption></figure>

| Option                    | Description                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------- |
| **click-cooldown-millis** | How long, in milliseconds, a player waits between two clicks on a sign. `0` turns it off. |
| **sounds.enabled**        | Plays the two sounds below. `false` keeps sign shops silent.                          |
| **sounds.success**        | Played when a sign transaction goes through. Uses the namespaced sound key.         |
| **sounds.failure**        | Played when a sign transaction is refused.                                          |

```yaml
sign-shops:
  click-cooldown-millis: 250
  sounds:
    enabled: true
    success: minecraft:entity.experience_orb.pickup
    failure: minecraft:block.note_block.bass
```

## Transactions

| Option | Description |
| --- | --- |
| **feedback** | Where the bought and sold message is shown: CHAT, ACTION\_BAR or NONE. The action bar shows the first line of the message, without the prefix. Error messages such as not enough money always go to chat. Also in **Editor > Settings > General**. |
| **confirm-above** | A purchase from a chest menu whose total is above this price opens a confirm screen first. `0` turns it off. A Bulk Buy always asks first, whatever this is set to. |

<figure><img src="../.gitbook/assets/editor-settings/confirm-above.png" alt="" width="563"><figcaption><p>Settings (Confirm Above)</p></figcaption></figure>

```yaml
transactions:
  feedback: CHAT
  confirm-above: 0
```

The confirm screen covers the buy menu, the bulk buy menu and instant buy clicks in a category, and its total includes any [price modifier](../add-ons/sell-boosters/README.md#price-modifiers). The green panes buy, while the red panes or Esc go back to the menu it came from. Each shop sets its look in [confirm.yml](customize-menus.md#confirm-menu), where it can also be turned off. Sales never ask. Bedrock forms use `bedrock.confirm-above` instead. Confirm Above is also set from Editor > Settings.

## Menus

With **escape-back** on, pressing Esc in a category, buy, sell or bulk menu opens the menu before it instead of closing. Only a close by the player counts, so a menu closed by the plugin or another plugin still closes. Off by default, and also set from Editor > Settings.

<figure><img src="../.gitbook/assets/editor-settings/escape-goes-back.png" alt="" width="563"><figcaption><p>Settings (Escape Goes Back)</p></figcaption></figure>

```yaml
menus:
  escape-back: false
```

## Locked Categories ⭐

How the main menu shows a category whose [conditions](../main-features/categories/edit-category.md#conditions) a player fails. LOCKED shows it with a locked line under its lore, and clicking it runs the deny actions of the failed checks or sends a message. HIDE leaves it out of the menu, and the categories after it move up. It can also be set from **Editor > Settings > General**.

```yaml
categories:
  locked-display: LOCKED
```

## IP Limit ⭐

How many accounts on one connection can buy an item that has a [player limit](../main-features/items/stock-and-restock.md#player-limit) between two restocks. The next account on that connection is refused until the item restocks, while each allowed account keeps its own player limit. It is on by default, and is also set from Editor > Settings.

<figure><img src="../.gitbook/assets/editor-settings/ip-limit.png" alt="" width="563"><figcaption><p>Settings (IP Limit)</p></figcaption></figure>

```yaml
ip-limit:
  enabled: true
  accounts: 1
```

Items without a player limit are not affected. With the Network add-on's shared stock, the IP limit is not applied.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/settings-file

---

# 📂 Shop Configuration File

> **Info:**
Everything on this page can be set from the in-game editor. The files are only worth opening for a bulk change, or to copy a shop between servers. Run /pshop reload after saving them.

## Where the Files Are

Each shop is one file, and each of its categories is one file in a folder named after the shop. The file name is the identifier, so renaming a shop by hand means renaming both its file and its folder.

```
shops/
├── shop.yml
└── shop/
    ├── blocks.yml
    └── valuables.yml
```

The plugin writes only the values that differ from the default, so a category of plain items stays short. Anything left out of the file takes its default.

## Shop File

```yml
open-command: shop
display-name: '<gradient:#FF9A00:#E52D27>Phoenix Shop</gradient>'
conditions:
  checks:
    vip:
      type: permission
      permission: shop.vip
currency:
  type: VAULT
currency-format: ''
enabled: true
actions:
  buy:
  - '[SOUND] ENTITY_ITEM_PICKUP; 1; 1'
  sell:
  - '[SOUND] ENTITY_EXPERIENCE_ORB_PICKUP; 1; 1'
  deny:
  - '[SOUND] BLOCK_NOTE_BLOCK_BASS; 1; 1'
  click:
  - '[SOUND] UI_BUTTON_CLICK; 0.5; 1'
  next-page:
  - '[SOUND] ITEM_BOOK_PAGE_TURN; 1; 1'
  previous-page:
  - '[SOUND] ITEM_BOOK_PAGE_TURN; 1; 1'
  add:
  - '[SOUND] UI_BUTTON_CLICK; 0.4; 1.4'
  remove:
  - '[SOUND] UI_BUTTON_CLICK; 0.4; 0.8'
  fill:
  - '[SOUND] ITEM_BUNDLE_INSERT; 1; 1'
  back:
  - '[SOUND] ITEM_BOOK_PAGE_TURN; 1; 0.8'
```

| Key                 | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **open-command**    | A command of its own that opens this shop, without the slash. Empty for none. A command another plugin already owns is left to that plugin. |
| **display-name**    | The name players see.                                                                        |
| **conditions**      | Who can open the shop, written like an item's [requirements](#requirements). Lite reads only `permission` checks. Empty lets everyone in. |
| **currency**        | What every item in the shop is priced in. See [Currency](#currency).                         |
| **currency-format** | How prices are written, such as `%amount% PlayerPoints`, `$%amount_short%` or `#,##0.00`. Empty uses the currency's own format. |
| **enabled**         | A disabled shop cannot be opened by anyone.                                                  |
| **actions**         | [Actions](../plugin-information/action-types.md) run on `buy`, `sell`, `deny`, `click`, `next-page`, `previous-page`, the amount buttons (`add`, `remove`), the fill button (`fill`) and a back button (`back`). An empty list runs nothing. A file that still has the old `sounds` section has each sound turned into one `[SOUND]` action the first time it loads. |

## Category File

```yml
enabled: true
title: '<bold><gradient:#56CCF2:#2F80ED>Armory</gradient></bold>'
icon: IRON_PICKAXE
order: 1
currency:
  type: SHOP
actions:
  open: []
  close: []
items:
  '0':
    identifier: iron_sword
    display-material: IRON_SWORD
    buy-price: 1000.0
  '1':
    identifier: iron_helmet
    display-material: IRON_HELMET
    buy-price: 1000.0
    sell-price: 250.0
```

| Key                | Description                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **enabled**        | A disabled category is hidden from players.                                                          |
| **title**          | The name players see.                                                                                |
| **icon**           | The button in the shop menu. A material, or a section with `material`, `display-name`, `lore`, `flags` and the other item keys. |
| **lore**           | Lines shown under the category in the main menu. Overrides the icon's own lore when set. Left out when empty. |
| **order**          | Categories are sorted by this number, then by identifier.                                            |
| **slot**           | A main menu category slot this category is pinned to. Left out, or `-1`, places it automatically.     |
| **buying**, **selling** | `false` stops every buy or every sale of this category's items. Left out when `true`.           |
| **conditions** ⭐  | Who can open the category and trade in it, written like the shop's `conditions`. Empty lets everyone in. |
| **sale** ⭐        | `percent` off the buy price of every item, with optional `from` and `until` dates, `days` and `time-window`. Only applies while `started` is `true`. See [Sale](../main-features/categories/edit-category.md#sale). |
| **currency** ⭐    | Overrides the shop's currency for this category. `SHOP` keeps the shop's.                            |
| **actions** ⭐     | Actions run on `open`, `close`, `buy`, `sell`, `deny`, `click`, `next-page` and `previous-page`. A non-empty list replaces the shop's own list for that moment. See [Action Types](../plugin-information/action-types.md). |
| **items**          | The items. The keys under it only keep the entries apart, and the order is the order players see.   |
| **click-mappings**  | What each click does in this category, in the same form as the global [click mappings](main-configuration.md#click-mappings). Clicks not listed use the global ones. |
| **messages**       | `buy`, `sell` and `cannot-afford`: messages that replace the normal ones for every item in this category. They take `%amount%`, `%item%`, `%price%`, `%currency%` and `%balance%`. Empty uses the normal message. |

## Item Keys

An item needs `identifier`, `display-material`, a price, and `purchase-items` or `purchase-commands` for what a purchase gives. Every other key is optional.

```yml
'2':
  identifier: vip_sword
  display-material: DIAMOND_SWORD
  amount: 1
  display-name: '&bVIP Sword'
  lore:
    - '&7Sharper than it looks.'
  enchants:
    - 'SHARPNESS:5'
  flags:
    - HIDE_ENCHANTS
  glow: true
  buy-price: 500.0
  sell-price: 100.0
  match-rule: EXACT
  stock: 60
  player-limit: 10
  restock:
    type: DAILY
    time: '04:00'
```

| Key                  | Description                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------- |
| **identifier**       | The item's name, used by stock counts and sign shops. Keep it unique within the category.   |
| **display-material** | The material. See [Materials](#materials).                                                  |
| **item-data**        | The whole item, encoded. Written by the editor when an item was added from your hand, such as a custom plugin item. Do not edit it. |
| **amount**           | The stack size shown, and how many one purchase gives.                                      |
| **display-name**     | The item's name. Empty keeps the material's own.                                            |
| **lore**             | The item's lore.                                                                            |
| **buy-price**        | What one purchase costs. `0` means it cannot be bought, unless `free` is on.                |
| **free**             | `true` lets players buy the item without paying, whatever `buy-price` says. Limits, stock and requirements still apply. |
| **sell-price**       | What one sale pays. `0` means it cannot be sold.                                            |
| **currency** ⭐      | Overrides the category's and the shop's currency for this item.                             |
| **match-rule**       | How closely a sold item has to match. See [Match Rule](#match-rule).                        |
| **enabled**          | A disabled item is hidden from players.                                                     |
| **purchase-items**   | What a purchase gives. The display item is never given. See [Purchase Items](#purchase-items). |
| **purchase-commands** | Commands run on a purchase. See [Commands](#commands).                                     |
| **sell-commands**    | Commands run on a sale.                                                                     |
| **sell-item**        | What a sale takes from the player, with `material`, `amount` and the [item properties](#item-properties). Its amount is how many one sale takes. Without it, a sale matches the display item. |
| **stock** ⭐         | How many are left to buy, shared by everyone. `-1` is unlimited.                            |
| **player-limit** ⭐  | How many one player may buy between restocks. `-1` is unlimited.                            |
| **sell-limit** ⭐    | How many one player may sell between restocks. `-1` is unlimited. |
| **limit-group** ⭐   | Items in the shop with the same group share one player limit and one sell limit. Empty for none. See [Limit Group](../main-features/items/stock-and-restock.md#limit-group). |
| **max-per-purchase** | The most lots one purchase can buy. `-1` is no limit.                                       |
| **min-sell**         | The fewest items one sale has to contain. `-1` is no minimum.                               |
| **damaged**          | `sell: true` lets worn tools and armour be sold, paid by the durability they have left; `min-percent` is the lowest share of the price they pay. |
| **restock** ⭐       | When a sold out item comes back. See [Restock](#restock).                                   |
| **available** ⭐     | When the item is for sale: `from` and `until` as `2026-10-25 18:00`, and a `window` such as `2h` after each restock. See [Availability](../main-features/items/stock-and-restock.md#availability). |
| **requirements** ⭐  | Checks a purchase or a sale has to pass. See [Requirements](#requirements).                 |
| **messages**         | `buy`, `sell` and `cannot-afford` for this item only, like a category's. An item's message wins over its category's. |

### Item Properties

These change how the item looks, and are also applied to what the player receives.

| Key                  | Format                                                                  |
| -------------------- | ----------------------------------------------------------------------- |
| **enchants**         | `SHARPNESS:5`. A custom enchantment works when its plugin is installed. |
| **flags**            | Item flags, such as `HIDE_ENCHANTS` or `HIDE_ATTRIBUTES`.               |
| **glow**             | `true` makes the item glow without an enchantment on it. 1.20.5+.       |
| **model-data**       | The custom model data number. `0` for none.                             |
| **item-model**       | An item model key, such as `minecraft:diamond`.                         |
| **tooltip-style**    | A tooltip style key.                                                    |
| **trim-material**    | An armour trim material, such as `GOLD`. Needs `trim-pattern` too.      |
| **trim-pattern**     | An armour trim pattern, such as `SENTRY`.                               |
| **potion-effects**   | `speed;1000;1`, the effect, its duration in ticks and its amplifier.    |
| **potion-type**      | The base potion of a potion or tipped arrow, such as `long_swiftness`.  |
| **instrument**       | The sound of a goat horn, such as `admire_goat_horn`.                   |
| **rgb**              | `255,0,0`, the colour of leather armour or a potion.                    |
| **banner-patterns**  | `RED;STRIPE_TOP`, a dye colour and a pattern.                           |
| **spawner-type**     | The mob a spawner spawns, such as `ZOMBIE`.                             |

## Materials

`display-material` takes a material name such as `DIAMOND`, a player head with its texture as `PLAYER_HEAD:<base64>`, or an item from another plugin with its prefix.

| Plugin            | Prefix              |
| ----------------- | ------------------- |
| ItemsAdder        | `itemsadder:`       |
| Nexo              | `nexo:`             |
| CraftEngine       | `craftengine:`      |
| MythicMobs items  | `mythicitem:`       |
| MMOItems          | `mmoitem:`          |
| ExecutableItems   | `executableitem:`   |
| ExecutableBlocks  | `executableblock:`  |
| Slimefun          | `slimefun:`         |
| HeadDatabase      | `hdb:`              |
| HeadDB            | `headdb:`           |
| PhoenixCrates     | `phoenixcrates:key:<key>`, `phoenixcrates:crate:<crate>` |

An item whose plugin is missing shows as dirt and cannot be bought or sold. The console names the item once.

## Currency

The same block is used by shops, categories and items.

| Type               | Description                                                                |
| ------------------ | -------------------------------------------------------------------------- |
| `SHOP`             | Categories and items only. Uses the currency above it.                     |
| `VAULT`            | Money, through Vault.                                                      |
| `PLAYERPOINTS`     | PlayerPoints.                                                              |
| `VOTINGPLUGIN`     | VotingPlugin points.                                                       |
| `EXCELLENTECONOMY` | An ExcellentEconomy currency, named in `identifier`.                       |
| `PHOENIXCURRENCIES` | A PhoenixCurrencies currency, named in `identifier`.                      |
| `EXPERIENCE`       | Experience points, or levels with `levels: true`.                          |
| `ITEM` ⭐          | An item used as money.                                                     |
| `PLACEHOLDER` ⭐   | Any number a PlaceholderAPI placeholder returns.                           |

```yml
currency:
  type: EXCELLENTECONOMY
  identifier: gems
```

```yml
currency:
  type: ITEM
  identifier: gold_coin
  item:
    display-name: Gold Coin
    material: GOLD_NUGGET
    match: EXACT
```

```yml
currency:
  type: PLACEHOLDER
  identifier: tokens
  placeholder:
    display-name: Tokens
    balance: '%tokenmanager_tokens%'
    buy: 'tokens remove %player% %amount_int%'
    sell: 'tokens add %player% %amount_int%'
```

A placeholder currency reads the balance from `balance`, and runs `buy` from the console to take the price and `sell` to pay it. `%player%`, `%amount%` and `%amount_int%` (rounded up) are filled in.

> **Info:**
The first item or placeholder currency with a given `identifier` defines it, so every other shop can use it by writing only the `type` and the `identifier`.

## Match Rule

How closely an item a player sells has to look like the shop item.

| Rule                  | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `EXACT`               | Everything must match: name, lore, enchantments and custom data.        |
| `MATERIAL_AND_NAME`   | The material and the display name must match.                           |
| `MATERIAL`            | Only the material matters.                                               |

> **Warning:**
Anything looser than `EXACT` lets a player buy something cheap, change it, and sell it back as something else. Only loosen it on items the shop does not sell.

## Purchase Items

A purchase gives these items, and selling matches against the first one. An item with no purchase items and no purchase commands cannot be bought, and one with no purchase items cannot be sold. Each entry takes `material`, `amount`, `display-name`, `lore` and the [item properties](#item-properties).

```yml
purchase-items:
  '0':
    material: SPAWNER
    spawner-type: COW
  '1':
    material: DIAMOND
    amount: 3
```

## Commands

`purchase-commands` run after a purchase and `sell-commands` after a sale, from the console. Start a line with `*` to run it as the player instead.

```yml
purchase-commands:
  - 'lp user %player% permission set essentials.fly'
  - '*spawn'
```

| Placeholder  | Value                                  |
| ------------ | -------------------------------------- |
| `%player%`   | The player's name                      |
| `%amount%`   | How many purchases were made           |
| `%item%`     | The item's name                        |
| `%price%`    | The total price                        |
| `%currency%` | The currency's name                    |
| `%shop%`     | The shop's name                        |

PlaceholderAPI placeholders work too. An item with purchase commands and no purchase items gives no item at all, only runs the commands.

## Restock

| Key | Used by | Description |
| --- | --- | --- |
| `type` | all | `NEVER`, `INTERVAL`, `DAILY`, `WEEKLY` or `MONTHLY`. |
| `every` | `INTERVAL` | How long after it sells out, such as `30m`, `6h` or `1d12h`. Units are `s`, `m`, `h` and `d`. |
| `time` | `DAILY`, `WEEKLY`, `MONTHLY` | The time of day, such as `'04:00'`. |
| `day` | `WEEKLY`, `MONTHLY` | A weekday such as `MONDAY`, or a day of the month from `1` to `28`. |

```yml
restock:
  type: WEEKLY
  day: MONDAY
  time: '04:00'
```

An item with no `restock` block never restocks.

## Requirements

Each check has a name of your choice, a `type`, the fields that type reads, and actions run when it fails. `applies-to` is `BOTH`, `BUY` or `SELL`, and `negate: true` flips the result. `minimum` is how many checks have to pass, and leaving it out means all of them.

```yml
requirements:
  minimum: 0
  checks:
    island-level:
      applies-to: BUY
      type: compare
      input: '%superior_island_level_int%'
      operator: '>='
      output: '7'
      deny-actions:
        - '[MESSAGE] &cYou need island level 7 to buy this.'
        - '[SOUND] BLOCK_NOTE_BLOCK_BASS; 1; 1'
    vip:
      type: permission
      permission: shop.vip
    java-only:
      type: platform
      platform: JAVA
```

| Type | Reads |
| --- | --- |
| `permission` | `permission` |
| `compare` | `input`, `operator`, `output` |
| `world` | `world` |
| `gamemode` | `gamemode` |
| `holding` | `material`, `name` and `whole-inventory`, all optional |
| `enchantment` | `enchantment` |
| `platform` | `platform`: `BEDROCK` or `JAVA` |
| `region` | `region`: a WorldGuard region id, needs WorldGuard |
| `world-time` | `time`: a range of world time such as `'08:00-14:45'` or `'22:00-06:00'` |
| `playtime` | `playtime`: such as `15m` or `5d 12h` |

`operator` is `>`, `>=`, `==`, `!=`, `<` or `<=` for numbers, or `equals`, `equals ignorecase`, `contains` or `not contains` for text.

`input` and `output` accept PlaceholderAPI placeholders. `holding` passes when the player holds an item, and when `material` is set, only one of that material. `name` also asks for that item name, compared without colors, and `whole-inventory: true` counts an item anywhere in the inventory instead of only the main hand. `enchantment` passes when the held item can take that enchantment. A type, operator or platform that does not exist refuses the transaction, even when negated, and is reported in the console once.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/configurations/shop-configuration-file

---

# 💎 Features

<table data-full-width="true"><thead><tr><th>Shops &#x26; Items</th><th>Buying &#x26; Selling</th><th>Management</th></tr></thead><tbody><tr><td>Customize via the In-Game Editor.</td><td>Buy and sell from the shop menus.</td><td>Import shops from ShopGUI+, EconomyShopGUI, UltimateShop, ExcellentShop, QuickShop and Essentials.</td></tr><tr><td>One file per shop and per category.</td><td>Bulk buy and bulk sell menus.</td><td>Edit the layout of every menu in-game.</td></tr><tr><td>Own command per shop, like <code>/shop</code>.</td><td>Configurable click actions (buy, sell, sell all).</td><td>Purchase history, with filters and CSV export ⭐.</td></tr><tr><td>Permission required to open a shop.</td><td><code>/sell hand</code>, <code>/sell inventory</code> and <code>/sell menu</code>.</td><td>Undo the last transaction. ⭐</td></tr><tr><td>Vault, PlayerPoints, VotingPlugin, ExcellentEconomy and PhoenixCurrencies currencies.</td><td>Sell menu that sells on close.</td><td>Search across every shop. ⭐</td></tr><tr><td>Experience points or levels as a currency.</td><td>Chest shops that players build themselves.</td><td>Price generator that prices a shop in a few clicks.</td></tr><tr><td>Item and Placeholder currencies. ⭐</td><td>Admin sign shops.</td><td>Price audit that finds money loops through crafting. ⭐</td></tr><tr><td>Currency per category and per item. ⭐</td><td>Limited stock with restocking. ⭐</td><td>Discord webhooks for 11 events. ⭐</td></tr><tr><td>Support for custom items (ItemsAdder, Nexo, CraftEngine, MMOItems, MythicItems and more).</td><td>Per-player purchase limits. ⭐</td><td>MySQL, MariaDB ⭐ and SQLite Database.</td></tr><tr><td>Custom heads through HeadDatabase and HeadDB.</td><td>Requirements with deny actions. ⭐</td><td>Folia supported.</td></tr><tr><td>Enchantments, trims, potion effects, colors and model data on items.</td><td>Open and close actions per category. ⭐</td><td>Bedrock forms through GeyserMC and Floodgate.</td></tr><tr><td>Spawners with a set mob type.</td><td>Give items or run commands on purchase.</td><td>MiniMessage and hex color support.</td></tr><tr><td>Three match rules for selling items back.</td><td>Run commands on sale.</td><td>Plugin Messages 100% configurable.</td></tr><tr><td>Custom enchantments from EcoEnchants and ExcellentEnchants.</td><td>Chat or action bar transaction feedback.</td><td>Developer API with events.</td></tr><tr><td>Category and shop-wide sales with a countdown. ⭐</td><td>Restock and sale alerts for every player who can buy the item. ⭐</td><td>Rank price modifiers with the Sell Boosters add-on. ⭐</td></tr><tr><td>Preview what an item gives before buying. ⭐</td><td>Sell a shulker box together with its contents.</td><td>Restock alerts on Discord. ⭐</td></tr></tbody></table>

## Add-ons

Add-ons load on Premium only.

<table data-full-width="true"><thead><tr><th>Add-on</th><th>What it adds</th></tr></thead><tbody><tr><td>AutoSell</td><td>Sell a player's inventory and placed sell chests on a timer.</td></tr><tr><td>Rotating Shop ⭐</td><td>Categories that show only some of their items, picked again on a schedule.</td></tr><tr><td>Sell Boosters ⭐</td><td>Sell multipliers, server-wide or for one player, with a duration.</td></tr><tr><td>Sell Wands ⭐</td><td>A wand that sells everything in a container with one right-click.</td></tr><tr><td>Network ⭐</td><td>Stock and sell limits counted once across every server on one database.</td></tr><tr><td>Shop Stands ⭐</td><td>A block that buys and sells one shop item, with the item and its prices floating above it.</td></tr></tbody></table>

## Suggestions

If you notice something missing from our plugin, please let us know. Additionally, we are always open to suggestions from our users to add more content and improve the plugin.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features

---

# 🔨 Auction House

> **Info:**
The Auction House is in both editions. The parts marked ⭐ need Premium; on Lite a player can have up to 10 listings, sells at a fixed price in the default currency and uses the built-in categories. It is on by default; set `enabled: false` in auction-house.yml to turn it off.

## Information

The Auction House lets players sell items to each other. A listing either has a fixed price that anyone can pay right away, or it is an auction that goes to the highest bidder when time runs out.

Expired items, won auctions and anything that did not fit in an inventory go to the player's collection bin, so nothing is lost while a player is offline. Players who were offline when something happened get the messages the next time they join.

## Selling

Hold the item and open the sell menu with `/ah sell`. Pick the listing type, the price, how long it stays up and, when more than one is allowed, the currency. `/ah sell <price>` and `/ah auction <starting bid>` ⭐ list the held item straight away with the default duration.

The **Price Guide** ⭐ in the sell menu shows what the same item sold for over the last days: the average and the last price for one item, and how many sold. Clicking it sets the price to the average for the amount being sold. Custom items from item plugins are told apart from the vanilla item they are made of.

The listing fee is paid when the item is listed and is not refunded. The sales tax is taken from what the seller receives.

## Bundles ⭐

`/ah bundle <price>` or `/ah bundle <starting bid> auction` opens a menu where the player puts up to 27 stacks that sell together as one listing. The buyer or winner gets every stack; players see the contents with Shift + Left-Click. Closing the menu without listing gives everything back.

## Buying and bidding

A fixed-price listing can be bought whole, or in part when partial buys are on. A bid ⭐ has to beat the current one by the minimum raise. The money is taken when the bid is placed and given back as soon as someone outbids the player or the auction is closed.

A bid in the last moments of an auction extends it, so nobody can win by bidding a second before the end.

A seller can cancel a listing until an auction has its first bid. Staff can remove any listing with Press Q: the item goes to the seller's collection bin and the highest bidder gets their money back.

## Watchlist and reminders ⭐

Shift + Right-Click on a listing adds it to the player's watchlist, found in **My Auctions**. Watchers are told about new bids and when the listing ends.

The highest bidder and everyone watching are reminded shortly before a listing ends, by default five minutes and one minute before. Reminders only reach players who are online at the time; they are not saved for the next join.

## Listing again ⭐

An expired item in the collection bin can go straight back up with Right-Click, at the same price and type, without taking it out first. The listing fee and limits apply again.

## Server Restock ⭐

The server can put items up for sale on its own at a set interval, so the Auction House is never empty on a quiet server. Server listings carry the server's seller name, sit between the player listings and are bought like any fixed-price listing in the first auction currency; the money goes to nobody.

Each item has an amount, a price and how many listings of it go up per restock. After a restock where every listing of an item sold, its price rises by the price rise; when some were left over, it drops by the price drop, never past the item's lowest and highest price. A random variation can move it a little more each time. Changing an item's price starts it over from there.

Unsold server listings disappear at the next restock when Replace Unsold is on, otherwise when they end. Nothing goes to a collection bin, and staff removing one deletes it. Turning the restock on runs one straight away; a restart waits out the rest of the interval. Items are added from the one in your hand in **Editor > Auction House > Features > Server Restock**, which keeps custom items exactly as held.

## Categories

The categories in the menu come from auction-house.yml, in the order they are written; an item goes into the first one it matches, and into **Other** when it matches none. Changing them or adding your own ⭐ needs Premium.

```yaml
categories:
  crate-keys:
    enabled: true
    name: Crate Keys
    icon: TRIPWIRE_HOOK
    data-keys:
    - phoenixcrates:key
  blocks:
    enabled: true
    name: Blocks
    icon: GRASS_BLOCK
    types:
    - BLOCKS
```

| Rule | Matches |
| ---- | ------- |
| `types` | Built-in groups: `BLOCKS`, `COMBAT`, `TOOLS`, `FOOD`, `POTIONS`, `ENCHANTED_BOOKS`, `ENCHANTED`. |
| `items` | Materials or custom item ids, such as `DIAMOND` or `nexo:pineapple`; a `*` at the end matches the start, such as `nexo:*`. |
| `name-contains` | Items whose name contains one of these texts. |
| `data-keys` | Items that carry one of these data keys, such as `phoenixcrates:key` for crate keys. |

Set `enabled: false` to hide a category.

## Settings

The command and its aliases are set with the other [commands](../configurations/main-configuration.md#commands), under `auction-house`.

> **Info:**
Everything below can be changed in **Editor > Auction House**, where Premium-only options show as locked on Lite, or in auction-house.yml followed by `/pshop reload`.

| Option | What it does |
| ------ | ------------ |
| `enabled` | Turns the Auction House and its command on or off. |
| `currencies` ⭐ | The currencies a seller can choose from, by currency id. Starts with `money`; empty uses the default currency. |
| `listing-limit` | How many listings a player can have at once. `-1` is unlimited. A higher limit can be given by permission ⭐. Lite allows at most 10. |
| `durations` | The durations a seller can choose from, such as `30m`, `6h` or `2d`. |
| `default-duration` | The duration used by `/ah sell <price>`, bundles and listing again, and preselected in the sell menu. |
| `min-price`, `max-price` | The lowest and highest price or starting bid. `max-price` also caps bids. |
| `currency-prices` ⭐ | A `min-price` and `max-price` per currency id, replacing the ones above for that currency. Set in **Prices > Per Currency**; `0` uses the ones above. |
| `listing-fee.flat`, `listing-fee.percent` | The fee to list an item: a fixed amount plus a percentage of the price. |
| `sales-tax` | The percentage taken from every sale. |
| `currency-taxes` ⭐ | A sales tax per currency id, replacing `sales-tax` for that currency. Set in **Prices > Per Currency**. |
| `item-taxes` ⭐ | A sales tax per material, custom item id or wildcard, replacing the others for that item. Items dropped into **Prices > Tax per Item** are added here. |
| `partial-buys` | Whether buyers can buy part of a stack. |
| `bids.increase-percent`, `bids.increase-minimum` | The minimum raise over the current bid: the larger of the percentage and the fixed amount. |
| `bids.cancel-with-bids` | Whether a seller can still cancel an auction that has bids. Bidders are refunded. |
| `anti-snipe.window`, `anti-snipe.extend` | A bid placed less than `window` seconds before the end makes the auction end `extend` seconds after that bid. `0` turns it off. |
| `ending-reminders` | When the highest bidder and watchers are reminded before the end, such as `5m` and `1m`. Empty turns it off. |
| `watchlist-limit` | How many listings one player can watch. `0` is unlimited. |
| `sell-cooldown` | Seconds a player has to wait between two listings. |
| `broadcast-new-listings` | Whether every player is told about new listings. |
| `disabled-worlds` | Worlds where players cannot list items. |
| `blacklist.items` | Materials, custom item ids or wildcards such as `*_spawn_egg` that cannot be listed. Items dropped into **Blocked Items** in the editor are added here. |
| `blacklist.exact-items` | Items with a name, lore or enchants dropped into **Blocked Items**. Only that exact item is blocked. |
| `blacklist.name-contains`, `blacklist.lore-contains` | Items whose name or a lore line contains one of these texts cannot be listed. |
| `allow-list.enabled`, `allow-list.items`, `allow-list.exact-items` ⭐ | When on, only these items can be listed. Items dropped into **Allowed Items** are added here, the same way as **Blocked Items**. |
| `price-guide.enabled`, `price-guide.days` ⭐ | The Price Guide in the sell menu, and how many days of sales it looks at. |
| `bundles.enabled`, `bundles.icon` ⭐ | Whether players can sell bundles, and the item that shows a bundle. |
| `server-restock.enabled`, `server-restock.interval` ⭐ | Whether the server restocks on its own, and how often, such as `6h` or `1d`. The shortest is `1m`. |
| `server-restock.seller-name`, `server-restock.duration` ⭐ | The seller name on server listings, and how long they stay up. |
| `server-restock.replace-unsold` ⭐ | Whether unsold server listings are taken down when the next restock starts. |
| `server-restock.price-change.up`, `.down`, `.random` ⭐ | The percentage a price rises after a sold-out restock, drops after one with leftovers, and moves at random each restock. |
| `server-restock.items` ⭐ | The items: `item` (a material or custom item id), `amount`, `price`, `min-price` and `max-price` (`0` is no limit), `stock` (listings per restock) and `enabled`. |

The tax is fixed when an item is listed, so a permission change later does not change what an existing listing pays. The blacklist and allow-list also apply to the contents of shulker boxes and bundles. Every message is in the translation file, under the `auction-house` section.

## Menus

Every menu can be laid out in game from **Editor > Auction House > Menus**, or changed in its file inside menus/auction-house: main.yml, sell.yml, bundle.yml ⭐, listings.yml, watchlist.yml ⭐, collection.yml, history.yml, preview.yml and one confirm menu per action, confirm-buy.yml, confirm-bid.yml ⭐, confirm-cancel.yml and confirm-remove.yml.

Bedrock players type prices, amounts, bids and searches in a form, and pick Shift and Press Q actions from a list. Java players get a dialog on Paper servers that support dialogs, and type in chat everywhere else.

## Discord

Listings, sales, bids, expired and removed listings and server restocks can be posted to Discord with the Premium edition, like the other [Discord Webhooks](discord-webhooks.md).

## Moving from another auction plugin

**Editor > Migrations** brings live listings, auctions, expired items and money still owed across from zAuctionHouse, PlayerAuctions, CrazyAuctions and Auction House (Kiranhart). Bids come across only when the old plugin took the bidder's money at bid time; otherwise the auction restarts at its price. Running it again skips what already came across. Remove the old plugin afterwards, since its files still hold everything.

## Placeholders

| Placeholder | Description |
| ----------- | ----------- |
| `%phoenixshop_ah_total%` | The number of listings on the auction house. |
| `%phoenixshop_ah_total_buy_now%`, `%phoenixshop_ah_total_auctions%` | The number of fixed-price listings and of auctions. |
| `%phoenixshop_ah_listings%` | The player's listings. |
| `%phoenixshop_ah_limit%` | The player's listing limit. |
| `%phoenixshop_ah_waiting%` | The entries in the player's collection bin. |
| `%phoenixshop_ah_winning%` | The auctions the player is the highest bidder on. |
| `%phoenixshop_ah_watching%` | The listings on the player's watchlist. |
| `%phoenixshop_ah_banned%` | Whether the player is banned from the auction house. |

## Files

| File | What it holds |
| ---- | ------------- |
| `PhoenixShop/auction-house.yml` | The settings above. |
| Plugin database | Listings, collection bins, sale history, watchlists, bans and messages waiting for offline players. |
| `PhoenixShop/translations/translations.<lang>.yml` | The messages, under `auction-house`. |

## Commands

| Command | Description |
| ------- | ----------- |
| `/ah` | Opens the auction house. |
| `/ah sell [price] [amount]` | Opens the sell menu, or lists the held item for a fixed price. |
| `/ah auction <starting bid> [amount]` ⭐ | Auctions the held item. |
| `/ah bundle <price> [buy-now\|auction]` ⭐ | Opens the bundle menu to sell several stacks as one listing. |
| `/ah find <item>` | Opens the auction house filtered by item or seller name. |
| `/ah listings` | Opens your listings. |
| `/ah collect` | Opens your collection bin. |
| `/ah history` | Shows what you bought and sold. |
| `/ah view <player>` | Shows every listing of one player. |
| `/ah open <player> <collection\|history>` ⭐ | Shows the collection bin or the history of one player. |
| `/ah ban <player>`, `/ah unban <player>` | Stops a player from listing, buying and bidding, or lets them again. |
| `/ah removeall <player> [confirm]` | Counts, then with `confirm` sends, every listing of one player to their collection bin and refunds every bid. |
| `/ah restock` ⭐ | Runs a server restock now. The next automatic one comes a full interval later. |

## Permissions

| Permission | What it allows | Default |
| ---------- | -------------- | ------- |
| `phoenixshop.auction.use` | Browsing, buying, bidding, the watchlist and the collection bin. | Everyone |
| `phoenixshop.auction.sell` | Listing items and bundles. | Everyone |
| `phoenixshop.auction.limit.<number>` ⭐ | A higher listing limit. `*` is unlimited. | - |
| `phoenixshop.auction.tax.<percent>` ⭐ | A lower sales tax; the lowest one the player has counts. | - |
| `phoenixshop.auction.admin` | Removing listings, `/ah view`, `/ah open`, `/ah ban`, `/ah unban`, `/ah removeall` and `/ah restock` ⭐. | Operators |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/auction-house

---

# 🪝 Discord Webhooks

> **Info:**
Everything on this page can be changed in **Editor > Settings > Discord Webhooks**, or in discord.yml followed by `/pshop reload`.

## Discord Webhooks

Phoenix Shop can post what happens in your shops to Discord: purchases, sales, chest shop trades, Auction House activity, price changes, stock running out, restock alerts, admin edits and a daily summary. Each kind of message can have its own webhook, so each can go to a different channel, or they can all share the default webhook. This is a Premium feature.

Messages are queued and sent in the background, so a slow or unreachable Discord never holds up a purchase.

## Setup

### Create the webhook

In Discord, open **Server Settings > Integrations > Webhooks**, create one for the channel you want the messages in, and copy its URL.

### Set it in the editor

Paste the URL into **Default Webhook** to use it for every message, or into the **Webhook URL** of one message to send that one somewhere else. Then turn on each message you want.

### Test it

**Send Test** in a message's screen posts a test message to its webhook. `/pshop webhooktest` does the same for the `anomaly` message and needs the `phoenixshop.admin` permission.

## Messages

| Message | Posted when | Shows |
| --- | --- | --- |
| purchase | A player buys from a shop. | Player, item, amount, price, currency and shop. |
| sale | A player sells to a shop. | Player, item, amount, price, currency and shop. |
| large-transaction | A purchase or sale costs or pays at least the threshold. | The same, plus whether it was a purchase or a sale. |
| price-change | The [price audit](price-audit.md) or the [price generator](price-generator.md) changes a price. | Shop, item, and the old and new price. |
| stock-depleted | An item with limited stock sells out. | Shop and item. |
| restock | An item with limited stock is restocked. | Shop, item and the new stock. |
| restock-alert | A [restock alert](restock-and-sale-alerts.md#restock-alerts) goes out. | Shop, item, whether it restocked or its sale window opened, and how many players were alerted. |
| player-shop-created | A player builds a chest shop. | Owner, item, mode, prices, currency and location. |
| player-shop-removed | A chest shop is removed. | Owner, item, mode, prices, currency and location. |
| chest-shop-trade | A player buys from or sells to a chest shop. | Customer, owner, whether they bought or sold, item, amount, price and location. |
| auction-listed | An item is listed on the [Auction House](auction-house.md). | Seller, item, price or starting bid, type and duration. |
| auction-sold | A listing sells or an auction is won. | Seller, buyer, item, price and type. |
| auction-bid | A player bids on an auction. | Bidder, seller, item, bid and number of bids. |
| auction-expired | A listing ends without selling. | Seller, item and price. |
| auction-removed | Staff take down a listing. | Staff member, seller and item. |
| auction-restocked | The server restocks the Auction House. | The number of new listings. |
| admin-edit | An admin changes anything in the editor. | Admin, shop, category, item, what changed and the new value. |
| daily-summary | Once a day, at the set time. | See below. |
| anomaly | `/pshop webhooktest` is run. | Who sent the test. |

The large transaction message is posted as well as the purchase or sale message, not instead of it. The restock alert message is posted even when no player was alerted.

## Options

Every message has the same options, with a few extras.

```yaml
discord:
  default-webhook-url: ''
  purchase:
    enabled: false
    webhook-url: ''
    username: Phoenix Shop
    avatar-url: ''
    embed:
      title: Purchase
      color: '#57f287'
  large-transaction:
    threshold: 10000
  chest-shop-trade:
    minimum-price: 0
  daily-summary:
    time: '00:00'
  restock-alert:
    message:
      restocked: '%item% is back in stock in %shop%.'
      window-opened: '%item% is on sale again in %shop%.'
```

| Option | Description |
| --- | --- |
| default-webhook-url | The webhook every message uses when it has no `webhook-url` of its own. Each message still has to be enabled. |
| enabled | Whether this message is posted at all. |
| webhook-url | The Discord webhook URL. Empty uses `default-webhook-url`; nothing is posted while both are empty. |
| username | The name the webhook posts under. |
| avatar-url | An image URL used as the webhook's avatar. Empty uses the webhook's own. |
| embed.title | The embed's heading. Empty uses the message's default title. |
| embed.color | The colour of the embed's side bar, as a hex value. |
| threshold | Large transaction only. The price at which a purchase or sale counts as large, in any currency. |
| minimum-price | Chest shop trade, auction listed, auction sold and auction bid only. Cheaper trades, listings and bids are not posted, so a busy server does not flood the channel. `0` posts everything. Trades paid in items are always posted. |
| time | Daily summary only. The time of day to post, as `HH:MM` on the server's clock. |
| message | Restock alert only. The text posted when the item restocks, and when it goes on sale again. `%item%` and `%shop%` are filled in. |

## Daily Summary

Posted once a day at the set time, covering the 24 hours before it: the number of purchases and sales, what players spent and were paid per currency, the most traded item, and the player who bought and the player who sold the most. Undone transactions are left out. A day with no transactions says so.

A time the plugin cannot read switches the summary off and leaves a warning in the console.

## Troubleshooting

If messages are not arriving, check the console. The plugin warns once per webhook, without printing the URL, when Discord refuses a post or cannot be reached.

* **The URL is wrong.** It must be the full `https://discord.com/api/webhooks/...` address, not a link to the channel.
* **The webhook was deleted in Discord.** The plugin keeps posting to an address that no longer exists until the URL is changed.
* **Rate limits.** When Discord asks the plugin to slow down, it waits and sends the rest after. Up to 64 messages wait in the queue, and anything past that is dropped, so a very busy shop with purchase, sale or chest shop trade messages on can lose some.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/discord-webhooks

---

# 🧩 In-Game Menu Editor

> **Info:**
The editor changes the same menu files described in [Customize Menus](../configurations/customize-menus.md). A menu saved in-game is live straight away, with no reload.

## Opening the Editor

There are two ways in, both needing `phoenixshop.command.editor`:

<figure><img src="../.gitbook/assets/in-game-menu-editor/in-game-menu-editor.png" alt="" width="563"><figcaption><p>Edit Shop (Edit Menus)</p></figcaption></figure>

* **Editor > Shops > \<shop> > Edit Menus** lists every menu of that shop. Left-click one to edit it.
* `/pshop editlayout <shop> <menu>` opens one menu directly. The menu is `main`, `buy`, `sell`, `bulk-buy`, `bulk-sell`, `sell-menu`, or the identifier of a category.

The menu opens as it looks to players, with every button in place. The main menu, for example, shows its category slots as lime panes where the categories will be.

> **Warning:**
While you edit, your hotbar holds the editor tools. Your own hotbar items are saved to a backup file first, and the editor does not open if that backup fails. They come back when you close the menu.

## Editing a Button

With no tool turned on, click any button to open its editor. Every field there changes that one button:

| Field | Description |
| --- | --- |
| Look | Drop an item here to copy its material, custom model data, item model and head texture. |
| Display Name | The name of the button. |
| Lore | The lore of the button. |
| Amount | How many are shown, 1 to 64. On a step button of the buy or sell menu, this is the step. |
| Glow | Makes the button glow. |
| Hide Attributes | Hides attack damage and similar lines. |
| Custom Model Data | The custom model data of the button. |
| Click Actions | The [menu actions](../configurations/customize-menus.md#menu-actions) run when the button is clicked. |
| Hide Tooltip | Hides the tooltip entirely. |
| Tooltip Style | The tooltip style, such as `minecraft:blue`. |
| Delete | Removes the button. |

A field only appears when the button has that option, and Delete only appears on decoration. The plugin's own buttons, such as Close or Confirm, can be moved and restyled but not deleted.

> **Warning:**
On the plugin's own buttons, players only see the material, amount, custom model data, name and lore. Glow, item model, hide tooltip and tooltip style take effect on decoration only.

## Drag and Drop

Pick up any item from your inventory and drop it:

* **On a button** to give the button that item's look: its material, custom model data, item model and head texture. The name, lore and actions stay.
* **On an empty slot** to add the item as new decoration, with its look, name and lore.

This is the quickest way to put a custom item from a resource pack or a textured head into a menu.

## Hotbar Tools

Right-click a tool while holding it, or click it in your inventory. The first three are modes: one is on at a time, it glows while on, and using it again turns it off.

| Slot | Tool | Description |
| --- | --- | --- |
| 1 | Reordering | Click a button, then click where it should go. If that slot is taken, the two buttons swap places. |
| 2 | Item Slots | Click an empty slot to add it to the menu's item slots, or click a lime slot to remove it. Also repeats decoration: click it to select it, then click empty slots to put it there too. Clicking decoration that already sits on several slots removes it from the slot you clicked. |
| 3 | New Button | Click an empty slot to place a new button there. Its editor opens straight away. |
| 4 | Add a Row | Makes the menu one row taller, up to 6. |
| 5 | Remove a Row | Makes the menu one row shorter, down to 1. |
| 8 | Menu Title | Type the new title, in a dialog where the server supports one, otherwise in chat. |
| 9 | Templates & Text | Opens the parts of the menu that have no slot of their own. |

The item slots are where the menu shows its own content: the categories on the main menu, the items on a category menu, the offers on a bulk menu and the drop area of the sell menu. A slot group always keeps at least one slot, and a button locked to a single slot cannot be repeated.

Removing a row does not delete what was on it. Anything left below the last row is hidden, you are told how many slots, and adding the row back shows it again.

## Templates & Text

Templates are buttons drawn once per entry rather than placed on a slot: the category tile of the main menu, the offer of a bulk menu, and the fill item of a category menu. Editing one restyles every copy of it. Their material is usually replaced by the category icon or the item, so only the name, lore and extras matter.

Text entries are the lines the menu adds by itself, such as the buy, sell and stock lines under every item of a category menu, or the no-permission lore of the buy and sell menus.

## Saving

Close the menu to save. The file is written, the menu is live for players at once, and your hotbar is given back. If you opened it from the Edit Menus list, the list opens again.

The menu is also saved when you leave the server, when you die, and when the server stops. Dying ends the session, and your own hotbar items drop with the rest of your inventory. If the server crashes mid-edit, your hotbar is given back the next time you join.

While editing, the tools cannot be dropped, placed or moved, and you cannot swap hands.

> **Info:**
Two admins can open the same menu at the same time. The second is warned, and whoever closes last overwrites the other's changes.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/in-game-menu-editor

---

# 👁️ Preview

> **Info:**
This feature is only available with the Premium Plan.

## Click Actions

The preview is reached through the `PREVIEW` click action. It is not mapped by default: add it to the [click mappings](../configurations/main-configuration.md#click-mappings) in config.yml, or to a category's own clicks in the editor.

```yaml
click-mappings:
  LEFT: BUY
  RIGHT: SELL
  SHIFT_LEFT: BUY
  SHIFT_RIGHT: PREVIEW
```

It works in category menus, and only on items that can be bought. On Lite it does nothing and is left out of the item's hint lines.

## Preview

`PREVIEW` opens a read-only menu showing what one purchase gives: the shop item with its price, and every purchase item with its amount. An item that also runs purchase commands says how many. An item that only runs commands shows the **empty** item. **Back** returns to the category.

The layout is on [Customize Menus](../configurations/customize-menus.md#preview-menu).

## Permission

| Permission | Description |
| --- | --- |
| phoenixshop.preview | Opens the preview with the `PREVIEW` click. Given to everyone by default. |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/preview

---

# 🔍 Price Audit

## Price Audit

A money loop is a way for a player to buy items, craft or smelt them into something else, and sell the result for more than they paid. Left in, one player can run it over and over and print money. The price audit walks the server's recipes against your prices and lists every loop it finds. This is a Premium feature.

<figure><img src="../.gitbook/assets/price-audit/price-audit.png" alt="" width="563"><figcaption><p>Editor (Price Audit)</p></figcaption></figure>

Open it from **Editor > Price Audit**, or run `/pshop audit` for the same list in chat. The editor's main page shows how many loops the last check found, on Lite too.

| Command | Permission | Description |
| --- | --- | --- |
| `/pshop audit` | phoenixshop.command.audit | Lists every money loop in chat, worst first. |

## What Is Checked

Every recipe the server knows is followed, up to four steps deep: crafting, smelting, blasting, smoking, campfire cooking, stonecutting, smithing and brewing. Custom recipes other plugins add are included.

Some items are left out because no player can farm them:

* Shops that are disabled, or that need a permission to open.
* Disabled categories.
* Items with limited stock or a per-player limit, since they run out.
* Sell prices on items with a custom name, lore, enchantments or model data, unless they sell by material only, since a plain crafted item does not match them.

Prices are only compared within one currency. A loop that buys in money and sells for gems is not reported.

## Loops From Sales and Boosters

Prices are checked twice: as listed, and at the lowest buy and highest sell price anything below could give. A loop that only shows up the second time is listed too, with an **Only with** line naming what causes it. A loop that already shows at listed prices is not listed twice.

| Effect | Counted when |
| --- | --- |
| [Category and shop sales](../main-features/categories/edit-category.md#sale) | Started and not ended, even outside its days or time window. The bigger of the two counts. |
| [Price modifiers](../add-ons/sell-boosters/README.md#price-modifiers) | The Sell Boosters add-on is installed. The cheapest buy and the best sell of any group with a permission. |
| [Sell boosters](../add-ons/sell-boosters/README.md) | Running and permission boosters that cover the item, combined by the add-on's stacking setting. |

Everything found stacks the way it does at checkout.

## Reading a Loop

Each loop shows the steps a player would take, then these details:

<figure><img src="../.gitbook/assets/price-audit/reading-a-loop.png" alt="" width="563"><figcaption><p>Price Audit (Gold Ingot)</p></figcaption></figure>

| Detail | Description |
| --- | --- |
| Severity | How bad the loop is, from the money back per run. |
| Profit | What one run of the loop makes. |
| Money Back | The profit as a share of what the player spent. |
| Currency | The currency the loop runs in. |
| Shop | The shop that pays too much for the final item. |
| Fix | The sell price that closes the loop. |
| Only with | What the loop needs, when it does not show at listed prices. |

| Severity | Money back |
| --- | --- |
| Critical | 100% or more. Every run at least doubles the player's money. |
| High | 25% or more. |
| Low | Anything under 25%. |

Loops are sorted by severity and profit together, so a loop that makes a lot per run comes before a cheap one with the same return. The **Filter Severity** button shows one severity at a time.

## Fixing a Loop

Left-clicking a loop in the editor asks to set the final item's sell price to the suggested fix, rounded down so it lands just under what making the item costs. Confirming writes the new price straight into the shop.

For an **Only with** loop the fix is worked out at the lowered buy prices, and sell multipliers are already taken out, so the boosted sell price still closes it.

If the item was removed, or its sell price is already at or below the fix, nothing is written and you are told the audit is out of date. Fixes are also posted to the price change [Discord webhook](discord-webhooks.md).

> **Info:**
A fix lowers one sell price. Raising the buy price of an ingredient closes the same loop, and is sometimes the better choice when the final item is sold elsewhere too. For an **Only with** loop, changing the sale, modifier or booster behind it works as well.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/price-audit

---

# 🧮 Price Generator

> **Info:**
The last 10 runs are saved in pricing.yml, so they can be undone.

## Price Generator

Pricing hundreds of items by hand is slow and easy to get wrong. The price generator prices a shop, or one of its categories, for the kind of economy you want. Raw items such as logs, ores and mob drops have a built-in value, and everything crafted from them is worked out from its recipe. The prices it writes are built so no craft can be bought, made and sold back at a profit.

<figure><img src="../.gitbook/assets/price-generator/price-generator.png" alt="" width="563"><figcaption><p>Editor (Price Generator)</p></figcaption></figure>

Open it from **Editor > Price Generator**, or with `/pshop prices`.

| Command | Permission | Description |
| --- | --- | --- |
| `/pshop prices` | phoenixshop.command.prices | Opens the price generator. |

## Shop and Category

Pick the shop, then either **Whole Shop** or a single category. Only the items there are priced.

<figure><img src="../.gitbook/assets/price-generator/shop-and-category.png" alt="" width="563"><figcaption><p>Price Generator (Whole Shop)</p></figcaption></figure>

## Economy

How easy it is to make money on your server. Each choice shows what a diamond would cost and sell for.

<figure><img src="../.gitbook/assets/price-generator/economy.png" alt="" width="563"><figcaption><p>Price Generator (Balanced)</p></figcaption></figure>

| Economy | Prices | Selling pays |
| --- | --- | --- |
| OP | 20 times Balanced | 80% of the buy price |
| Easy | Twice Balanced | 50% of the buy price |
| Balanced | Diamond 250, iron ingot 21 | 25% of the buy price |
| Hard | Same as Balanced | 10% of the buy price |

Prices are rounded to a sensible step for their size, buy prices up and sell prices down, so rounding never opens a loop.

## Preview

Lists every item that would change, with its current and new buy and sell price in the item's currency. Nothing is written until you apply.

<figure><img src="../.gitbook/assets/price-generator/preview.png" alt="" width="563"><figcaption><p>Price Generator (Iron Ingot)</p></figcaption></figure>

## Apply

Overrides the current prices with the ones in the preview, after a confirmation. Every changed price is posted to the price change [Discord webhook](discord-webhooks.md) ⭐.

<figure><img src="../.gitbook/assets/price-generator/apply.png" alt="" width="563"><figcaption><p>Price Generator (Apply)</p></figcaption></figure>

## Undo

Puts back the prices from the last run, and each press goes one run further back. A price changed by hand since that run is kept.

<figure><img src="../.gitbook/assets/price-generator/undo.png" alt="" width="563"><figcaption><p>Price Generator (Undo)</p></figcaption></figure>

## What Is Priced

- A price that is off stays off, so an item that is only sold keeps no buy price. An item with neither price gets both.
- Items are priced by what they are, so a custom name, lore or model does not matter. Enchanted items, items from item plugins, items with purchase or sell commands, and items with more than one purchase item keep their price.
- Items with no recipe and no built-in value, such as spawners and spawn eggs, keep their price.

> **Info:**
Run the [Price Audit](price-audit.md) after applying. A price you set by hand elsewhere can still leave a loop the generator did not create.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/price-generator

---

# 📜 Purchase History & Undo

## Purchase History

Every purchase and sale is stored in the plugin's database: who made it, in which shop, what item, how many, the price and the currency. The purchase history lets you browse all of it, on Lite too. The parts marked ⭐ need Premium, and show as locked on Lite.

<figure><img src="../.gitbook/assets/purchase-history/purchase-history.png" alt="" width="563"><figcaption><p>Editor (Purchase History)</p></figcaption></figure>

Open it from **Editor > Purchase History**, or with `/pshop history`. The editor first asks which trades to show, so each list stays short:

| Type | Shows |
| --- | --- |
| Shops | Purchases and sales in the shop menus. |
| Chest Shops | Trades at player and admin chest shops. Each row names the shop's owner, or its name, says whether the shop still exists and, while it does, where it is. Shift + left-click a row to teleport to that shop ⭐. |
| Sign Shops | Purchases and sales on admin sign shops. |

`/pshop history` shows shop menus and sign shops together. Trades at player shops are only listed under Chest Shops, and they are never counted in sales statistics or the daily summary, and never undone with `/pshop undo`.

| Command | Permission | Description |
| --- | --- | --- |
| `/pshop history` | phoenixshop.command.history | Opens the history for everyone. |
| `/pshop history <player>` | phoenixshop.command.history | Opens the history already filtered to one player. |
| `/pshop history export [player] [shop]` ⭐ | phoenixshop.command.history | Writes the history to a CSV file. Use `*` as the player to export everyone. Works from the console. |

The list shows the newest transactions first, each with the item, the amount, the price, the shop and how long ago it happened. The item and amount are what actually changed hands, so a sale shows the sell item rather than the shop icon. It refreshes by itself while open, so new transactions appear without reopening it. An undone transaction stays in the list, marked as undone.

Clicking a transaction filters the list to the player who made it ⭐.

## Player ⭐

Shows only one player's transactions. Left-click and type the player's name, or leave it empty for everyone. Right-click clears it. Any player who has joined the server can be picked, online or not.

<figure><img src="../.gitbook/assets/purchase-history/player.png" alt="" width="563"><figcaption><p>Purchase History (Player)</p></figcaption></figure>

## Filters ⭐

Narrows the list further. Right-click clears every filter except the player.

<figure><img src="../.gitbook/assets/purchase-history/filters.png" alt="" width="563"><figcaption><p>Purchase History (Filters)</p></figcaption></figure>

| Filter | Description |
| --- | --- |
| Shop | Only the transactions of one shop. Not offered for player shops. |
| Item | Only one item. The list offers only items that appear in this history, in the chosen shop if one is picked. Changing the shop clears the item. |
| Type | Only purchases, or only sales. |
| Time | All time, the last hour, today, the last 7 days or the last 30 days. |

## Totals

What the transactions in the list add up to: how many there were, how many items were bought and sold, and how much players spent and were paid, per currency. Undone transactions are left out.

<figure><img src="../.gitbook/assets/purchase-history/totals.png" alt="" width="563"><figcaption><p>Purchase History (Totals)</p></figcaption></figure>

## Export ⭐

Writes every transaction matching the current player and filters to a CSV file in the exports folder, ready for a spreadsheet. The file name carries the filters and the time, so exports never overwrite each other.

<figure><img src="../.gitbook/assets/purchase-history/export.png" alt="" width="563"><figcaption><p>Purchase History (Export)</p></figcaption></figure>

The file has one row per transaction with these columns: time, player, shop, kind, item, lots, items, price, currency and undone.

## Undo ⭐

`/pshop undo` lets a player take back their own most recent transaction, a few seconds after a misclick. A purchase is returned for a refund, and a sale is bought back for the money it paid. The exact items and amount of money move back, so a sold tool returns with its wear and enchantments.

| Command | Permission | Description |
| --- | --- | --- |
| `/pshop undo` | phoenixshop.undo | Reverses your last transaction. Given to everyone by default. |

Undo is set in config.yml, and has no editor option.

```yaml
undo:
  enabled: true
  window-seconds: 30
```

| Option | Description |
| --- | --- |
| enabled | Turns `/pshop undo` on or off for everyone. |
| window-seconds | How long after a transaction it can still be undone. |

Running it again undoes the transaction before, as long as that one is still inside the window. Each transaction can only be undone once.

An undo is refused, with nothing moved, when:

* The player no longer carries exactly what they bought. A renamed, enchanted or partly used copy does not count.
* The player no longer has the money a sale paid them.
* The inventory has no room for the items a sale took.
* The transaction's currency is not available right now.
* The purchase only ran commands and gave no items.

> **Info:**
Undo only reads the main inventory and hotbar. Items that were bought into the off-hand have to be moved into the inventory first.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/purchase-history-and-undo

---

# 📢 Restock & Sale Alerts

> **Info:**
This feature is only available with the Premium Plan.

## Who Is Alerted

An alert goes to every online player who can open the shop and buy the item: the shop, its category and the item are enabled, the category is not hidden and is buying, the item is buyable and usable, and the player meets both the shop's and the category's conditions. The player also needs `phoenixshop.alerts`, given to everyone by default, and must not have turned alerts off.

| Command | Permission | Description |
| --- | --- | --- |
| `/pshop alerts toggle` | phoenixshop.alerts | Turns your restock and sale alerts off or on. The choice is kept across relogs. |

## Restock Alerts

Players are told when an item comes back:

* **Restocked** - the item restocks on its own, with `/pshop stock restock`, or with `/pshop stock set` to more than 0.
* **On sale again** - the item's [availability](../main-features/items/stock-and-restock.md#availability) opens, at its Available From time or when its sale window opens.

An item restocked while its sale window is closed does not alert until the window opens, and a window that opens on an item with no stock left does not alert. Sale windows are checked every 20 seconds, and the first check after a start or a reload only notes which items are on sale, so it never alerts.

Restock alerts can also be posted to Discord with the [restock-alert webhook](discord-webhooks.md#messages).

## Display

Whether alerts are sent at all, and whether they show in chat, as a title or with a sound, is set in config.yml, see [Main Configuration](../configurations/main-configuration.md#restock-and-sale-alerts). The wording is the `restock-alerts` translations.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/restock-and-sale-alerts

---

# 🔎 Search

> **Info:**
This feature is only available with the Premium Plan.

## Search

`/pshop search` opens a menu listing every item across the shops the player can open. Typing terms narrows the list by name, and the results can be sorted. Clicking a result opens its category, on the page that holds it. When nothing matches, a barrier in the middle of the results says so.

<figure><img src="../.gitbook/assets/search/search.png" alt="" width="563"><figcaption><p>Search</p></figcaption></figure>

| Command | Permission | Description |
| --- | --- | --- |
| `/pshop search [terms]` | phoenixshop.search | Searches every shop by name. Without terms, lists everything. |
| `/pshop search hand` | phoenixshop.search | Searches every shop for the item in the main hand. |

Both are given to everyone by default. Bedrock players using forms get the results as a form.

## Search by Item

Instead of a name, a search can look for one item. Vanilla items match by material, and also by the shop item's [selling rule](../main-features/items/edit-item.md#selling-rule). Items from other plugins, such as ItemsAdder, Nexo or MMOItems, match by their namespaced id.

<figure><img src="../.gitbook/assets/search/search-by-item.png" alt="" width="563"><figcaption><p>Search (Search By Item)</p></figcaption></figure>

There are two ways to set the item:

* `/pshop search hand`, holding the item.
* The **Search By Item** button of the search menu. Click it with an item on the cursor to search for that item, or with an empty cursor to clear the filter. The item stays on the cursor.

When a name and an item are both set, a result has to match both.

## Excluded Shops

Shops left out of the search results, by identifier. Case does not matter. It is set in config.yml, and has no editor option.

```yaml
search:
  excluded-shops: []
```

The layout of the menu is covered on [Customize Menus](../configurations/customize-menus.md#search-menu).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/features/search

---

# 🔌 First Installation

## Installation

1. Download the jar from our website.
2. Install PhoenixShop-?.jar (or PhoenixShopLite-?.jar) into your "Plugins" folder.
3. Install an economy plugin for the currency you want to use, such as Vault with an economy provider.
4. Start your server.
5. Configure the plugin by yml file or by in-game editor `/pshop editor`.

<figure><img src=".gitbook/assets/editor/editor.gif" alt="" width="563"><figcaption><p>The in-game editor</p></figcaption></figure>

On the first start the plugin creates one shop, opened with `/shop`, with two example categories.

> **Info:**
Coming from another shop plugin? Your shops can be imported from **Editor > Migrations** instead of building them again.

## Add-on Installation

1. Download the add-ons you wish to install.
2. Drag and drop them into the `PhoenixShop\addons` folder. Add-ons need the Premium version.
3. Restart your server.

> **Info:**
We strongly advise using the latest STABLE build of the plugin, as it includes the most recent bug fixes.

## Version Support

The plugin supports Spigot, any Spigot forks, Paper and any Paper forks. It should also work on any custom modded servers.

> **Warning:**
Folia is supported, but the support is still **experimental**. Test it on a staging server before putting it in front of your players, and report anything you run into.

<table><thead><tr><th>Minecraft Version</th><th data-type="checkbox"></th></tr></thead><tbody><tr><td>26.x</td><td>true</td></tr><tr><td>1.21.x</td><td>true</td></tr><tr><td>1.20.4 - 1.20.6</td><td>true</td></tr><tr><td>1.20.3 and older</td><td>false</td></tr></tbody></table>

Bedrock players joining through GeyserMC get Bedrock forms instead of chest menus when Floodgate or Geyser is installed.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/first-installation

---

# 🪧 Admin Signs

> **Info:**
Lite holds up to 20 admin signs across the server, and Premium has no limit. Signs made on Premium beyond that keep working after a downgrade.

> **Info:**
Signs are kept in the plugin's database, one record per identifier. An old admin\_signs folder is moved there on first start and renamed admin\_signs.migrated. The text all signs share is in the sign-shops section of settings.yml.

## Information

An admin sign is a server-owned sign linked to one item of one of your shops. Clicking it buys or sells that item without opening a menu. It trades exactly as the shop does: the same prices, currency, stock, purchase limits and requirements apply, and it sends the same messages.

<figure><img src="../../.gitbook/assets/sign-shops/sign-shops.png" alt="" width="563"><figcaption><p>Editor (Sign Shops)</p></figcaption></figure>

Unlike a [player shop](../player-shops/), it needs no container and the server supplies the items.

## Create a Sign

Write \[pshop] on the first line of a sign and click Done, anywhere, on a container or not. An [admin chest shop](../player-shops/README.md#admin-shops) is made by left-clicking a container instead. This needs `phoenixshop.sign.admin`. The sign shows as not linked and its editor opens straight away, with a Status button listing what is still missing. Pick the shop, the category and the item, and click Status once everything is ticked. See [Edit Sign](#edit-sign).

<figure><img src="../../.gitbook/assets/sign-shops/create-a-sign.png" alt="" width="563"><figcaption><p>Sign Shops (Create Sign)</p></figcaption></figure>

To edit a sign later, look at it and run `/pshop editshop`, or open it from the sign list.

Only a player with `phoenixshop.sign.admin` can break an admin sign. Breaking it deletes the sign.

## Using a Sign

| Click | Buy sign | Sell sign | Buy & Sell sign |
| --- | --- | --- | --- |
| Right-Click | Buys | Nothing | Buys |
| Left-Click | Nothing | Sells | Sells |

A plain click moves the sign's [Amount](#amount). A sneaking click runs the sign's own [shift-click action](#shift-left-click) instead, such as buying a stack or selling everything. When that action is Nothing, or buys on a sell-only sign or sells on a buy-only sign, the sneaking click falls back to the plain click.

After a purchase, the player is told how much stock is left and how many more they may buy, when the item has either limit.

## Sign Shops List

**Editor > Sign Shops** lists every admin sign, with its mode, shop, category, item, the buy and sell price it trades at, and its location. A sign whose shop, category or item no longer exists is marked as not linked.

<figure><img src="../../.gitbook/assets/sign-shops/sign-shops-list.png" alt="" width="563"><figcaption><p>Sign Shops (New Sign)</p></figcaption></figure>

Left-click a sign to edit it, shift + left-click to teleport to it, and right-click to delete it after a confirmation. Turn on Reordering to sort the list: click a sign, then click the one it should swap places with.

## Edit Sign

> **Info:**
Every change is saved to the sign's file and redrawn on the sign as you make it. There is no save button.

### Identifier

The unique id of the sign, and the name of its file. A new sign gets a generated one such as `sign_4821`. Only letters, numbers, `-` and `_` are allowed, and two signs cannot share one. Renaming renames the file.

<figure><img src="../../.gitbook/assets/edit-sign/identifier.png" alt="" width="563"><figcaption><p>Sign Shop (Identifier)</p></figcaption></figure>

### Display

Opens the sign's icon and display name. Both are only used in the [Sign Shops list](#sign-shops-list), so staff can tell signs apart. They do not change what the sign shows in the world.

<figure><img src="../../.gitbook/assets/edit-sign/display.png" alt="" width="563"><figcaption><p>Sign Shop (Display)</p></figcaption></figure>

### Permission Requirement

Restricts the sign to players with a permission. When it is off, anyone can use the sign. When it is on and no node is typed, the node is `phoenixshop.signs.use.<shop>`, named after the linked shop. `phoenixshop.signs.use.*` opens every sign.

<figure><img src="../../.gitbook/assets/edit-sign/permission-requirement.png" alt="" width="563"><figcaption><p>Sign Shop (Permission Requirement)</p></figcaption></figure>

### Shop

The shop the sign trades from, picked from a list. Changing it clears the category and the item.

<figure><img src="../../.gitbook/assets/edit-sign/shop.png" alt="" width="563"><figcaption><p>Sign Shop (Shop)</p></figcaption></figure>

### Category

The category of the item, picked from the chosen shop. Changing it clears the item.

<figure><img src="../../.gitbook/assets/edit-sign/category.png" alt="" width="563"><figcaption><p>Sign Shop (Category)</p></figcaption></figure>

### Item

The item the sign trades, picked from the chosen category. The sign stores the item's identifier, so reordering the category does not repoint it.

<figure><img src="../../.gitbook/assets/edit-sign/item.png" alt="" width="563"><figcaption><p>Sign Shop (Item)</p></figcaption></figure>

> **Warning:**
Renaming or deleting the shop, category or item leaves the sign not linked. It shows the not-linked text and refuses every click until it is linked again.

### Mode

Whether the sign buys, sells or both. A mode the item has no price for is marked as missing its buy or sell price and cannot be chosen. When the item changes and the current mode no longer fits, the sign switches to one that does.

<figure><img src="../../.gitbook/assets/edit-sign/mode.png" alt="" width="563"><figcaption><p>Sign Shop (Mode)</p></figcaption></figure>

### Amount

How many lots one plain click moves. A lot is the item's own amount, so an item sold in 16s with an Amount of 2 moves 32. The most allowed is one full stack of the item, and the value is lowered on its own when the item changes. It can only be set once an item is picked.

<figure><img src="../../.gitbook/assets/edit-sign/amount.png" alt="" width="563"><figcaption><p>Sign Shop (Amount)</p></figcaption></figure>

### Shift + Left Click

What a sneaking left-click does. By default it sells a stack.

<figure><img src="../../.gitbook/assets/edit-sign/shift-left-click.png" alt="" width="563"><figcaption><p>Sign Shop (Shift + Left Click)</p></figcaption></figure>

### Shift + Right Click

What a sneaking right-click does. By default it buys a stack.

<figure><img src="../../.gitbook/assets/edit-sign/shift-right-click.png" alt="" width="563"><figcaption><p>Sign Shop (Shift + Right Click)</p></figcaption></figure>

Both shift-click options offer the same choices, and each choice needs its own permission on top of the sign's.

| Choice | Does | Permission |
| --- | --- | --- |
| Nothing | Falls back to the plain click. | None |
| Buy a Stack | Buys one full stack of the item. | `phoenixshop.signs.buy-stack` |
| Sell a Stack | Sells up to one full stack from the inventory. | `phoenixshop.signs.sell-stack` |
| Fill Inventory | Buys as many as fit in the inventory and the player can afford. | `phoenixshop.signs.buy-inventory` |
| Sell Everything | Sells every matching item in the inventory. | `phoenixshop.signs.sell-all` |

### Copy Settings

Copies the shop, category, item, mode, amount, permission and both shift-click actions of another sign onto this one. The identifier and display stay as they are. It is the fastest way to put up a row of signs for the same item.

<figure><img src="../../.gitbook/assets/edit-sign/copy-settings.png" alt="" width="563"><figcaption><p>Sign Shop (Copy Settings)</p></figcaption></figure>

### Delete Sign

Deletes the sign after a confirmation. The sign block stays in the world, blank, and its file is removed.

<figure><img src="../../.gitbook/assets/edit-sign/delete-sign.png" alt="" width="563"><figcaption><p>Sign Shop (Delete Sign)</p></figcaption></figure>

> **Danger:**
This option is permanent, and signs can't be restored.

### Status

Only shown while setting up a sign that was just placed. It lists what the sign still needs: a shop, a category, an item, and a mode the item has a price for. Once every line is ticked, click it to close the editor.

## Sign Text

> **Info:**
The sign text is set in the sign-shops section of settings.yml. It has no editor option, and `/pshop reload` applies a change to every sign.

### Lines

Every admin sign is drawn from the four-line template of its mode. Changing a template restyles every sign that uses it at once.

```yaml
sign-shops:
  lines:
    buy:
    - '&5&l[Shop]'
    - '&0%item% &fx%amount%'
    - '&cBuy %buy_price%'
    - ''
    sell:
    - '&5&l[Shop]'
    - '&0%item% &fx%amount%'
    - '&aSell %sell_price%'
    - ''
    both:
    - '&5&l[Shop]'
    - '&0%item% &fx%amount%'
    - '&cBuy %buy_price%'
    - '&aSell %sell_price%'
    not-linked:
    - '&5&l[Shop]'
    - '&4Not Linked'
    - '&8%id%'
    - '&8Ask an Admin'
```

A sign whose shop, category or item is missing uses not-linked, so a broken sign is obvious in the world.

### Placeholders

| Placeholder | Description |
| --- | --- |
| %id% | The identifier of the sign. |
| %name% | The display name of the sign. |
| %shop% | The display name of the linked shop. |
| %category% | The display name of the linked category. |
| %item% | The name of the linked item. |
| %amount% | How many items one click moves. |
| %buy\_price% | The price of one click when buying. |
| %sell\_price% | The price of one click when selling. |
| %stock% | The stock left of the item. |
| %mode% | The mode of the sign. |

A value that does not apply, such as the buy price of an item that cannot be bought, shows as `-`. Unlimited stock shows as `∞`.

### Redrawing

Signs are redrawn when a shop is edited, when prices change, when an item restocks and when the chunk they are in loads. After a transaction, only signs of that item are redrawn, and only when a template uses %stock%.

A sign whose block has been destroyed, by a player, an explosion, fire or a piston, is removed on its own and the removal is logged in the console.

## Settings

> **Info:**
These options are in **Editor > Sign Shops > Settings** and are saved to the sign-shops section of settings.yml. They apply to every admin sign at once.

### Sign Shops

Turns [player shops](../player-shops/README.md) on or off. It does not affect admin signs. See [Player Shops Settings](../player-shops/settings.md#enabled).

<figure><img src="../../.gitbook/assets/sign-shop-settings/sign-shops.png" alt="" width="563"><figcaption><p>Sign Shops</p></figcaption></figure>

### Click Cooldown

How many milliseconds a player waits between two transactions on admin signs. Clicks inside the cooldown are ignored without a message, which stops a held mouse button from buying dozens of times. The cooldown is per player and shared by every sign. The default is 250, the most is 5000, and 0 turns it off.

<figure><img src="../../.gitbook/assets/sign-shop-settings/click-cooldown.png" alt="" width="563"><figcaption><p>Sign Shops (Click Cooldown)</p></figcaption></figure>

### Transaction Sound

The sound played when a sign transaction goes through, written as a sound key such as `minecraft:entity.experience_orb.pickup`. Type `none` to play nothing.

<figure><img src="../../.gitbook/assets/sign-shop-settings/transaction-sound.png" alt="" width="563"><figcaption><p>Sign Shops (Transaction Sound)</p></figcaption></figure>

### Refused Sound

The sound played when a sign transaction is refused, for example for lack of money or room. Type `none` to play nothing.

<figure><img src="../../.gitbook/assets/sign-shop-settings/refused-sound.png" alt="" width="563"><figcaption><p>Sign Shops (Refused Sound)</p></figcaption></figure>

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/admin-signs

---

# ✏️ Edit Sign

> **Info:**
Every change is saved to the sign's file and redrawn on the sign as you make it. There is no save button.

## Identifier

The unique id of the sign, and the name of its file. A new sign gets a generated one such as `sign_4821`. Only letters, numbers, `-` and `_` are allowed, and two signs cannot share one. Renaming renames the file.

<figure><img src="../../.gitbook/assets/edit-sign/identifier.png" alt="" width="563"><figcaption><p>Sign Shop (Identifier)</p></figcaption></figure>

## Display

Opens the sign's icon and display name. Both are only used in the [Sign Shops list](./#sign-shops-list), so staff can tell signs apart. They do not change what the sign shows in the world.

<figure><img src="../../.gitbook/assets/edit-sign/display.png" alt="" width="563"><figcaption><p>Sign Shop (Display)</p></figcaption></figure>

## Permission Requirement

Restricts the sign to players with a permission. When it is off, anyone can use the sign. When it is on and no node is typed, the node is `phoenixshop.signs.use.<shop>`, named after the linked shop. `phoenixshop.signs.use.*` opens every sign.

<figure><img src="../../.gitbook/assets/edit-sign/permission-requirement.png" alt="" width="563"><figcaption><p>Sign Shop (Permission Requirement)</p></figcaption></figure>

## Shop

The shop the sign trades from, picked from a list. Changing it clears the category and the item.

<figure><img src="../../.gitbook/assets/edit-sign/shop.png" alt="" width="563"><figcaption><p>Sign Shop (Shop)</p></figcaption></figure>

## Category

The category of the item, picked from the chosen shop. Changing it clears the item.

<figure><img src="../../.gitbook/assets/edit-sign/category.png" alt="" width="563"><figcaption><p>Sign Shop (Category)</p></figcaption></figure>

## Item

The item the sign trades, picked from the chosen category. The sign stores the item's identifier, so reordering the category does not repoint it.

<figure><img src="../../.gitbook/assets/edit-sign/item.png" alt="" width="563"><figcaption><p>Sign Shop (Item)</p></figcaption></figure>

> **Warning:**
Renaming or deleting the shop, category or item leaves the sign not linked. It shows the not-linked text and refuses every click until it is linked again.

## Mode

Whether the sign buys, sells or both. A mode the item has no price for is marked as missing its buy or sell price and cannot be chosen. When the item changes and the current mode no longer fits, the sign switches to one that does.

<figure><img src="../../.gitbook/assets/edit-sign/mode.png" alt="" width="563"><figcaption><p>Sign Shop (Mode)</p></figcaption></figure>

## Amount

How many lots one plain click moves. A lot is the item's own amount, so an item sold in 16s with an Amount of 2 moves 32. The most allowed is one full stack of the item, and the value is lowered on its own when the item changes. It can only be set once an item is picked.

<figure><img src="../../.gitbook/assets/edit-sign/amount.png" alt="" width="563"><figcaption><p>Sign Shop (Amount)</p></figcaption></figure>

## Shift + Left Click

What a sneaking left-click does. By default it sells a stack.

<figure><img src="../../.gitbook/assets/edit-sign/shift-left-click.png" alt="" width="563"><figcaption><p>Sign Shop (Shift + Left Click)</p></figcaption></figure>

## Shift + Right Click

What a sneaking right-click does. By default it buys a stack.

<figure><img src="../../.gitbook/assets/edit-sign/shift-right-click.png" alt="" width="563"><figcaption><p>Sign Shop (Shift + Right Click)</p></figcaption></figure>

Both shift-click options offer the same choices, and each choice needs its own permission on top of the sign's.

| Choice | Does | Permission |
| --- | --- | --- |
| Nothing | Falls back to the plain click. | None |
| Buy a Stack | Buys one full stack of the item. | `phoenixshop.signs.buy-stack` |
| Sell a Stack | Sells up to one full stack from the inventory. | `phoenixshop.signs.sell-stack` |
| Fill Inventory | Buys as many as fit in the inventory and the player can afford. | `phoenixshop.signs.buy-inventory` |
| Sell Everything | Sells every matching item in the inventory. | `phoenixshop.signs.sell-all` |

## Copy Settings

Copies the shop, category, item, mode, amount, permission and both shift-click actions of another sign onto this one. The identifier and display stay as they are. It is the fastest way to put up a row of signs for the same item.

<figure><img src="../../.gitbook/assets/edit-sign/copy-settings.png" alt="" width="563"><figcaption><p>Sign Shop (Copy Settings)</p></figcaption></figure>

## Delete Sign

Deletes the sign after a confirmation. The sign block stays in the world, blank, and its file is removed.

<figure><img src="../../.gitbook/assets/edit-sign/delete-sign.png" alt="" width="563"><figcaption><p>Sign Shop (Delete Sign)</p></figcaption></figure>

> **Danger:**
This option is permanent, and signs can't be restored.

## Status

Only shown while setting up a sign that was just placed. It lists what the sign still needs: a shop, a category, an item, and a mode the item has a price for. Once every line is ticked, click it to close the editor.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/admin-signs/edit-sign

---

# ⚙️ Settings

> **Info:**
These options are in **Editor > Settings > Sign Shops** and are saved to the sign-shops section of settings.yml. They apply to every admin sign at once.

## Sign Shops

Turns [player shops](../player-shops/) on or off. It does not affect admin signs. See [Player Shops Settings](../player-shops/settings.md#enabled).

<figure><img src="../../.gitbook/assets/sign-shop-settings/sign-shops.png" alt="" width="563"><figcaption><p>Sign Shops</p></figcaption></figure>

## Click Cooldown

How many milliseconds a player waits between two transactions on admin signs. Clicks inside the cooldown are ignored without a message, which stops a held mouse button from buying dozens of times. The cooldown is per player and shared by every sign. The default is 250, the most is 5000, and 0 turns it off.

<figure><img src="../../.gitbook/assets/sign-shop-settings/click-cooldown.png" alt="" width="563"><figcaption><p>Sign Shops (Click Cooldown)</p></figcaption></figure>

## Transaction Sound

The sound played when a sign transaction goes through, written as a sound key such as `minecraft:entity.experience_orb.pickup`. Type `none` to play nothing.

<figure><img src="../../.gitbook/assets/sign-shop-settings/transaction-sound.png" alt="" width="563"><figcaption><p>Sign Shops (Transaction Sound)</p></figcaption></figure>

## Refused Sound

The sound played when a sign transaction is refused, for example for lack of money or room. Type `none` to play nothing.

<figure><img src="../../.gitbook/assets/sign-shop-settings/refused-sound.png" alt="" width="563"><figcaption><p>Sign Shops (Refused Sound)</p></figcaption></figure>

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/admin-signs/settings

---

# 📝 Sign Text

> **Info:**
The sign text is set in the sign-shops section of settings.yml. It has no editor option, and `/pshop reload` applies a change to every sign.

## Lines

Every admin sign is drawn from the four-line template of its mode. Changing a template restyles every sign that uses it at once.

```yaml
sign-shops:
  lines:
    buy:
    - '&5&l[Shop]'
    - '&0%item% &fx%amount%'
    - '&cBuy %buy_price%'
    - ''
    sell:
    - '&5&l[Shop]'
    - '&0%item% &fx%amount%'
    - '&aSell %sell_price%'
    - ''
    both:
    - '&5&l[Shop]'
    - '&0%item% &fx%amount%'
    - '&cBuy %buy_price%'
    - '&aSell %sell_price%'
    not-linked:
    - '&5&l[Shop]'
    - '&4Not Linked'
    - '&8%id%'
    - '&8Ask an Admin'
```

A sign whose shop, category or item is missing uses not-linked, so a broken sign is obvious in the world.

## Placeholders

| Placeholder | Description |
| --- | --- |
| %id% | The identifier of the sign. |
| %name% | The display name of the sign. |
| %shop% | The display name of the linked shop. |
| %category% | The display name of the linked category. |
| %item% | The name of the linked item. |
| %amount% | How many items one click moves. |
| %buy\_price% | The price of one click when buying. |
| %sell\_price% | The price of one click when selling. |
| %stock% | The stock left of the item. |
| %mode% | The mode of the sign. |

A value that does not apply, such as the buy price of an item that cannot be bought, shows as `-`. Unlimited stock shows as `∞`.

## Redrawing

Signs are redrawn when a shop is edited, when prices change, when an item restocks and when the chunk they are in loads. After a transaction, only signs of that item are redrawn, and only when a template uses %stock%.

A sign whose block has been destroyed, by a player, an explosion, fire or a piston, is removed on its own and the removal is logged in the console.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/admin-signs/sign-text

---

# 🗂️ Categories

> **Info:**
Every category is its own file inside the shop's folder in shops, named after the category's identifier.

## Add a Category

Left-click the lime stained glass in **Editor > Shops > Shop > Categories** to create a category. It gets the next free `category_<number>` identifier and its editor opens straight away.

<figure><img src="../../.gitbook/assets/categories/categories.png" alt="" width="563"><figcaption><p>Edit Shop (Categories)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/categories/add-a-category.png" alt="" width="563"><figcaption><p>Categories (New Category)</p></figcaption></figure>

Every category in the list shows its icon, display name and identifier, how many items it holds and whether it is enabled. Left-click one to edit it, right-click it to delete it, together with its items, after a confirmation. The Filter button narrows the list to enabled categories, disabled categories, categories on the main menu, hidden categories or subcategories.

## Order

Categories fill the category slots of the shop's main menu by their order number, lowest first, and by identifier when two share the same number. The same order sorts sub-categories inside their parent. Disabled, [hidden](edit-category.md#hidden) and [sub-categories](edit-category.md#parent-category) are skipped. There is no editor option for it, so it is set in the category's file, and a new category starts at 0.

```yaml
order: 1
```

> **Info:**
When a shop has more categories than its main menu has category slots, the rest go on further pages. Without page buttons in the layout they are hidden, and the console says so.

## Navigation

| Features | Description |
| --- | --- |
| [Identifier](edit-category.md#identifier) | The unique id of the category and the name of its file. |
| [Display](edit-category.md#display) | The title, icon and lore of the category. |
| [Currency](edit-category.md#currency) | Override the shop's currency and its format for this category. |
| [Open Command](edit-category.md#open-command) | A command that opens the category directly. |
| [Hidden](edit-category.md#hidden) | Keep the category out of the main menu and search. |
| [Parent Category](edit-category.md#parent-category) | Show the category inside another one. |
| [Items](../items/) | The items of the category. |
| [Actions](edit-category.md#actions) | Actions run when the category is opened or closed. |
| [Conditions](edit-category.md#conditions) | Who can open the category and trade in it. |
| [Rotation](edit-category.md#rotation) | Show only some of the items at a time. |
| [Sale](edit-category.md#sale) | A discount on every item of the category. |
| [Buying](edit-category.md#buying) | Allow or block buying from the category. |
| [Selling](edit-category.md#selling) | Allow or block selling to the category. |
| [Enabled](edit-category.md#enabled) | Show or hide the category. |
| [Delete](edit-category.md#delete) | Delete the category and its items. |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/categories

---

# ✏️ Edit Category

> **Info:**
Every option on this page is saved to the category's own file inside the shop's folder in shops.

Trading, Sale and Actions are grouped under **Trading & Actions**. Every other option is on the category editor itself. The back button returns to the category list.

## Identifier

The unique id of the category inside its shop, and the name of its file. Spaces are not allowed, and two categories of the same shop cannot share one.

<figure><img src="../../.gitbook/assets/categories/identifier.png" alt="" width="563"><figcaption><p>Edit Category (Identifier)</p></figcaption></figure>

> **Danger:**
Stock counts are stored against the category's identifier. Changing it starts the stock of every item in the category over.

## Display

The icon of this option is the category's own icon. Clicking it opens the two settings that decide how the category looks in the shop's main menu.

<figure><img src="../../.gitbook/assets/categories/display.png" alt="" width="563"><figcaption><p>Edit Category (Display)</p></figcaption></figure>

### Icon

Drop an item on the slot to use it as the category's icon.

<figure><img src="../../.gitbook/assets/categories/icon.png" alt="" width="563"><figcaption><p>Display (Icon)</p></figcaption></figure>

### Display Name

The title of the category, shown on its icon in the main menu. Color codes are supported. It cannot be empty.

<figure><img src="../../.gitbook/assets/categories/display-name.png" alt="" width="563"><figcaption><p>Display (Display Name)</p></figcaption></figure>

### Lore

The lines shown under the category's name in the main menu, wherever `%category_lore%` is used. When set, it overrides the lore of the icon item. Left empty, the icon item's own lore is used.

<figure><img src="../../.gitbook/assets/categories/lore.png" alt="" width="563"><figcaption><p>Display (Lore)</p></figcaption></figure>

## Currency

Prices every item of this category in another currency than the shop's. Items that set their own currency still use theirs. Left-click swaps between the currency types, starting at the shop's own, and right-click opens the chosen type to pick the currency. The types are listed on [Currencies](../currencies/).

<figure><img src="../../.gitbook/assets/categories/currency.png" alt="" width="563"><figcaption><p>Edit Category (Currency)</p></figcaption></figure>

> **Info:**
This feature is only available with the Premium Plan.

### Currency Format

How the prices of this category are written, with the same patterns as the [shop's format](../shops/edit-shop.md#currency-format). It is set from the right-click menu of the Currency option, also while the category keeps the shop's currency. Left empty, the shop's format is used. Items that set their own currency keep the shop's format.

## Open Command

A command of its own that opens this category directly, without the slash. Leave it empty for no command. It works like the [shop's open command](../shops/edit-shop.md#open-command): adding a player's name opens it for them, and a command another plugin, shop or category already uses is skipped and the console says so.

<figure><img src="../../.gitbook/assets/categories/open-command.png" alt="" width="563"><figcaption><p>Edit Category (Open Command)</p></figcaption></figure>

The shop's and the category's conditions are checked as on a normal opening, and a disabled category does not open. A hidden category still opens. The back button leads to the parent category, or to the shop's main menu.

## Hidden

A hidden category is left out of the shop's main menu and of search results, but stays reachable through its open command, `/pshop open`, the [CATEGORY action](../../plugin-information/action-types.md#open-a-category) and its parent category.

<figure><img src="../../.gitbook/assets/categories/hidden.png" alt="" width="563"><figcaption><p>Edit Category (Hidden)</p></figcaption></figure>

## Parent Category

Places this category inside another category of the same shop instead of the main menu. Sub-categories are shown with their icon, name and lore at the start of the parent's item list, ordered by their [order](README.md#order), and share its pages. Their back button returns to the parent, and they can be nested to any depth.

<figure><img src="../../.gitbook/assets/categories/parent-category.png" alt="" width="563"><figcaption><p>Edit Category (Parent Category)</p></figcaption></figure>

The list only offers categories that would not make this one its own ancestor. A file that sets such a parent, or one that does not exist, is shown at the top level and the console says so. Deleting a category moves its sub-categories to the top level.

## Items

Opens the items of this category. The option shows how many there are. See [Items](../items/).

<figure><img src="../../.gitbook/assets/categories/items.png" alt="" width="563"><figcaption><p>Edit Category (Items)</p></figcaption></figure>

## Actions

Lists of actions run at moments in this category, such as a message, a sound, a title or a command: Open and Close, Buy and Sell when a purchase or sale goes through, Deny when one is refused, Click when an item is clicked, and Previous Page and Next Page. In Buy, Sell and Deny, `%item%`, `%amount%`, `%price%`, `%currency%` and `%balance%` are filled in.

<figure><img src="../../.gitbook/assets/categories/actions.png" alt="" width="563"><figcaption><p>Trading (Actions)</p></figcaption></figure>

Open runs when the player enters the category and Close when they leave it: closing the menu, going back, logging out or opening another category, a subcategory included. The buy, sell, bulk, confirm and preview screens of its items count as inside the category, so going into one and back runs neither.

Buy, Sell, Deny, Click and the page lists replace the shop's matching [actions](../shops/edit-shop.md#actions) for this category. Leave one empty to keep the shop's.

> **Info:**
This feature is only available with the Premium Plan.

## Click Mappings

What each click does on this category's items, such as Shift + Right-Click selling everything. Each click can be left on Default, which uses the global [click mappings](../../configurations/main-configuration.md#click-mappings), or set to its own action.

<figure><img src="../../.gitbook/assets/categories/click-mappings.png" alt="" width="563"><figcaption><p>Edit Category (Click Mappings)</p></figcaption></figure>

## Conditions

Who can open this category and buy or sell in it, with the same checks as the [shop's conditions](../shops/edit-shop.md#conditions). A player who fails them gets the deny actions of the failed checks, or a message when there are none, whether they come from the main menu, search, a quick buy or sell command, a sign, a stand or an NPC. `/sell` and the other sell-everything features skip the category for them.

<figure><img src="../../.gitbook/assets/categories/conditions.png" alt="" width="563"><figcaption><p>Edit Category (Conditions)</p></figcaption></figure>

In the main menu a locked category is either shown with a locked line under its lore or hidden, depending on [Locked Categories](../../configurations/settings-file.md#locked-categories).

> **Info:**
This feature is only available with the Premium Plan.

## Rotation

Makes this category show only some of its items at a time, picked again on a schedule. Turn **Rotating** on to start it, then set the [rotation settings](../../add-ons/rotating-shop/#settings). Turning it off shows every item again and forgets the settings. Needs the [Rotating Shop](../../add-ons/rotating-shop/) add-on.

## Trading

Turns Buying and Selling on or off for this category, each ticked in the list. Right-click the highlighted one to switch it.

<figure><img src="../../.gitbook/assets/categories/trading.png" alt="" width="563"><figcaption><p>Trading</p></figcaption></figure>

### Buying

Turned off, nothing in this category can be bought anywhere: menus, quick buy commands, signs, stands and NPC trades all refuse, and the buy lines and buy click hints disappear from the items.

### Selling

Turned off, nothing in this category can be sold anywhere: menus, quick sell commands, `/sell`, sell-all, sell wands, AutoSell, signs and stands all skip or refuse it, and the sell lines and sell click hints disappear from the items.

## Sale

Takes a percentage off the buy price of every item in the category. The discount goes through the same price pipeline as [price modifiers](../../add-ons/sell-boosters/README.md#price-modifiers) and stacks with them, so the struck-through price and every price placeholder stay correct. While this category has no running sale of its own, a [shop-wide sale](../shops/edit-shop.md#sale) applies to it.

<figure><img src="../../.gitbook/assets/categories/sale.png" alt="" width="563"><figcaption><p>Trading (Sale)</p></figcaption></figure>

The `%sale%` badge shows on discounted items and on the category's icon in the main menu while the sale runs. Under it, the icon counts down every second to the moment the discount stops: Ends, or the end of its day or time window, whichever comes first.

| Option | Description |
| --- | --- |
| Starts | When the sale starts. Not set starts it right away. |
| Ends | When the sale ends. Not set keeps it running. |
| Days | The days of the week it runs on. No day picked runs it every day. |
| Time Window | The time of day it runs between. An end before the start runs past midnight, so 22:00 to 02:00 is a night sale. Not set runs it all day. |

All four have to match for the discount to apply. Times use the server's clock and time zone.

### Start and Stop

Nothing on the Sale screen reaches players until **Start Sale** is clicked, so a sale can be set up in full before it goes live. Starting needs a discount above 0, and setting the discount back to 0 stops the sale. **Stop Sale** ends it at once and keeps every setting for the next start. The button, and the Sale button one screen up, show where the sale stands:

<figure><img src="../../.gitbook/assets/categories/start-and-stop.png" alt="" width="563"><figcaption><p>Sale (Stop Sale)</p></figcaption></figure>

| Status | Meaning |
| --- | --- |
| Not started | The sale is stopped. |
| Starts in | Started, but before Starts or outside its Days and Time Window. Counts down to the next moment the discount applies, with its date. |
| Running | The discount applies right now. The Sale button one screen up counts down the time left instead. |
| No end | Running with no Ends, Days or Time Window to stop it. |
| Ended | Ends has passed, or no later moment matches. Move Ends or clear it to run the sale again. |

A sale saved before this button existed with a discount above 0 is started once on load, so it keeps running after an update.

### Date and Time Pickers

Starts and Ends open a date picker with a button each for year, month, day, hour and minute. Left-click adds 1 and right-click takes 1 away; with shift held they move by 10 years, 6 months, 7 days, 6 hours or 5 minutes. Each part wraps around on its own, and the day is kept inside the length of the month, leap years included. **Now** picks the current server time, **Clear** removes the date, **Confirm** saves it and the back button leaves without saving.

<figure><img src="../../.gitbook/assets/categories/date-and-time-pickers.png" alt="" width="563"><figcaption><p>Starts (Year)</p></figcaption></figure>

Time Window opens a screen with a Start and an End time picker, which work the same way with hour and minute only, and is saved once both are set. Days opens seven day toggles with buttons to turn every day on or off.

Right-click on any of these fields to type the value instead, as `2026-10-25 18:00`, `18:00-22:00` or `SATURDAY, SUNDAY`.

> **Info:**
This feature is only available with the Premium Plan.

## Enabled

A disabled category keeps its items but is hidden from the shop's main menu and its parent category, cannot be opened by command or action, and nothing in it can be bought or sold: `/sell`, sell wands, AutoSell and sign shops all skip it.

<figure><img src="../../.gitbook/assets/categories/enabled.png" alt="" width="563"><figcaption><p>Edit Category (Enabled)</p></figcaption></figure>

## Delete

Deletes the category together with its file and all of its items, after a confirmation.

<figure><img src="../../.gitbook/assets/categories/delete.png" alt="" width="563"><figcaption><p>Edit Category (Delete)</p></figcaption></figure>

> **Danger:**
This option is permanent, and categories can't be restored.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/categories/edit-category

---

# 💰 Currencies

> **Info:**
A currency is saved on the shop, category or item that uses it, in the shop's own files in the shops folder.

Every price in the plugin is paid in a currency. A shop always has one, and a category or an item can set its own on Premium. Whatever does not set one uses the one above it: an item falls back to its category, and a category to its shop.

<figure><img src="../../.gitbook/assets/currencies/currencies.png" alt="" width="563"><figcaption><p>Settings (Currencies)</p></figcaption></figure>

| Type | Needs | Edition | Section |
| --- | --- | --- | --- |
| Vault | Vault and an economy plugin such as EssentialsX | Lite | [Economy Plugins](#vault) |
| PlayerPoints | PlayerPoints | Lite | [Economy Plugins](#playerpoints) |
| VotingPlugin | VotingPlugin | Lite | [Economy Plugins](#votingplugin) |
| ExcellentEconomy | ExcellentEconomy | Lite | [Economy Plugins](#excellenteconomy) |
| PhoenixCurrencies | PhoenixCurrencies | Lite | [Economy Plugins](#phoenixcurrencies) |
| Experience | Nothing | Lite | [Experience](#experience) |
| PlaceholderAPI | PlaceholderAPI | Premium | [Placeholder Currencies](placeholder-currencies.md) |
| Item | Nothing | Premium | [Item Currencies](#item-currencies) |

A type whose plugin is not installed, or that needs Premium on Lite, is skipped when you swap through the types in the editor.

## In the Shop File

The currency is a block with its type on the shop, the category or the item. A category or item without a block uses the one above it.

```yaml
currency:
  type: EXCELLENTECONOMY
  identifier: gems
```

The type is one of `VAULT`, `PLAYERPOINTS`, `VOTINGPLUGIN`, `EXCELLENTECONOMY`, `PHOENIXCURRENCIES`, `EXPERIENCE`, `PLACEHOLDER` or `ITEM`. ExcellentEconomy, PhoenixCurrencies, Placeholder and Item also take an identifier naming which currency of that type to use, and Placeholder and Item currencies are written out in full in the same block, shown on [Placeholder Currencies](placeholder-currencies.md#in-the-shop-file) and under [Item Currency in the Shop File](#item-currency-in-the-shop-file).

## When a Plugin Is Missing

A shop priced in a currency the server cannot pay in does not open, and tells the player which plugin is missing. An item priced in such a currency is hidden from its shop until the plugin is installed, and `/sell` skips it.

## Whole Numbers and Decimals

Vault, Placeholder and decimal ExcellentEconomy currencies accept decimal prices. Vault rounds them to the cent, up when the player pays and down when the player is paid, so a total of `2.005` costs `2.01` and pays `2.00`. PlayerPoints, VotingPlugin, Experience, Item and whole-number ExcellentEconomy currencies are whole numbers only: a decimal price is rounded up when the player pays and rounded down when the player is paid, so `2.5` costs `3` and pays `2`. A PhoenixCurrencies currency is rounded the same way to the number of decimals it is set to. The rounded amount is the one named in the transaction message, stored in the history and moved back by undo.

## Currencies Screen

**Editor > Settings > Currencies** lists every currency the server knows, with the plugin behind it and whether that plugin is installed. Placeholder currencies can be created, edited and deleted from here. The other types are built in and only listed.

<figure><img src="../../.gitbook/assets/currencies/currencies-screen.png" alt="" width="563"><figcaption><p>Currencies (Money)</p></figcaption></figure>

## Economy Plugins

These currencies hand the balance over to another plugin. The plugin has to be installed and enabled before its type can be picked, and a shop priced in one that goes missing stops opening until it is back.

<figure><img src="../../.gitbook/assets/economy-plugins/economy-plugins.png" alt="" width="563"><figcaption><p>Edit Shop (Currency)</p></figcaption></figure>

### Vault

The server's main money, through [Vault](https://www.spigotmc.org/resources/vault.34315/). Vault holds no money by itself, so an economy plugin such as EssentialsX has to be installed alongside it. New shops are priced in Vault.

Vault does not run on Folia. Install [VaultUnlocked](https://modrinth.com/plugin/vaultunlocked) in its place, with an economy plugin that supports Folia.

Prices are written in the economy plugin's own format. Decimal prices are rounded to the cent, up when a player pays and down when a player is paid.

### PlayerPoints

Points from [PlayerPoints](https://modrinth.com/plugin/playerpoints). Points are whole numbers, so a decimal price is rounded up when a player pays and down when a player is paid.

### VotingPlugin

Vote points from [VotingPlugin](https://www.spigotmc.org/resources/votingplugin.15358/). Like PlayerPoints, they are whole numbers only.

### ExcellentEconomy

Any currency set up in [ExcellentEconomy](https://www.spigotmc.org/resources/excellenteconomy.106334/). Right-click the currency option in the editor and click **Currency** to pick one from a searchable list of every ExcellentEconomy currency. In the shop file, the currency's ExcellentEconomy id is its identifier.

Whether decimals are allowed is decided by ExcellentEconomy per currency, and prices are written in that currency's own format. A currency without decimals is rounded like PlayerPoints.

> **Info:**
ExcellentEconomy balances are only read and changed for players who are online.

### PhoenixCurrencies

Any currency set up in PhoenixCurrencies. Right-click the currency option in the editor and click **Currency** to pick one from a searchable list of every PhoenixCurrencies currency. In the shop file, the currency's PhoenixCurrencies id is its identifier.

Prices are rounded to the number of decimals the currency is set to, up when a player pays and down when a player is paid, and written in that currency's own format. Balances are read and changed for offline players too.

An id already taken by a built-in or ExcellentEconomy currency, such as `money`, keeps pointing at that currency.

## Experience

A built-in currency that needs no other plugin. It is paid in experience points by default, or in levels when levels are turned on. Paying never takes a player below 0. Prices are written as `10 XP` or `10 Levels`.

### Points or Levels

Right-click the currency button in the editor and turn on **Count In Levels** to charge and pay levels instead of experience points. In the shop file, `levels: true` on an `EXPERIENCE` block turns levels on.

```yaml
currency:
  type: EXPERIENCE
  levels: true
```

Each shop, category and item has its own block, so one shop can price in points and another in levels. Both are whole numbers: a decimal price is rounded up when a player pays and down when a player is paid.

> **Info:**
A level costs more experience the higher it is, so 5 levels are worth far more to a level 50 player than to a level 5 one. Points cost every player the same.

## Item Currencies

An Item currency makes players pay with an item they carry, such as emeralds, a custom coin or a named token, instead of money. This is a Premium feature and needs no other plugin.

Each shop, category or item gets its own Item currency, so a shop can be priced in diamonds while one of its categories is priced in emeralds.

### Currency Item

Pick the Item type on the shop, category or item, right-click it, and drop the item players should pay with into the slot. Only one of it is stored, whatever the stack size. Right-click the slot to get a copy of the stored item.

Name, lore, enchantments and custom data are kept, so a renamed paper can be a voucher that plain paper does not count as.

The same screen changes the stored item's name and lore without dropping it in again. MiniMessage, `&` codes and hex colours all work.

### Paying and Being Paid

Items are whole numbers, so a decimal price is rounded up when a player pays and down when a player is paid. Paying takes matching items from anywhere in the inventory. Being paid puts the items into the inventory, and anything that does not fit is dropped at the player's feet.

Prices are written as the amount followed by the item's name, such as `12 Emerald`. The item's own name is used with its colours. Set **Currency Display** on the same screen to write a different name instead, such as `&fDiamond Sword` for an item named `&c&lDIAMOND SWORD`. Item prices are whole numbers, so this type has no Currency Format.

### Item Currency in the Shop File

```yaml
currency:
  type: ITEM
  identifier: item_shop
  item:
    display-name: Emerald
    material: EMERALD
    item-data: ''
    match: EXACT
```

| Option | Description |
| --- | --- |
| display-name | The Currency Display: the name written after prices. Empty uses the item's own name, colours included. |
| material | The item, when it has nothing special on it. |
| item-data | The full item, written by the editor when the item has a name, lore or other data. It wins over the material. |
| match | How closely a carried item has to match. See below. |

| Match | What counts |
| --- | --- |
| EXACT | Only an identical item: same name, lore, enchantments and data. The default. |
| MATERIAL\_AND\_NAME | The same material with the same display name. |
| MATERIAL | Any item of the same material. |

> **Warning:**
Loosen the match only for plain items. With MATERIAL, a renamed voucher and an ordinary copy of the same material pay the same.

## Symbols and Formats

### How Prices Are Written

Every currency writes prices its own way. Vault, ExcellentEconomy and PhoenixCurrencies use the economy plugin's format, PlayerPoints writes `20 PlayerPoints`, VotingPlugin `20 Vote Tokens`, Experience `10 XP` or `5 Levels`, and Placeholder and Item currencies add their display name. A shop can replace this with a format of its own.

### Currency Format

How prices in one shop are written, set by right-clicking the shop's Currency option. Write `%amount%` where the number goes, and anything around it is shown as typed, so `%amount% PlayerPoints` writes `20 PlayerPoints` and `$%amount%` writes `$20`. Leave it empty to keep the currency's own format.

Write `%amount_short%` instead for a shortened number with a `k`, `m`, `b` or `t` suffix, so `$%amount_short%` writes `$1.5k` for 1500 and `$2.3m` for 2300000. Amounts under 1000 are written in full.

The format replaces the currency's own format completely, so put any symbol or name you want shown into it.

| Format | 1234.56 is written as |
| --- | --- |
| `%amount% PlayerPoints` | 1,234.56 PlayerPoints |
| `$%amount%` | $1,234.56 |
| `$%amount_short%` | $1.2k |
| `#,##0.00` | 1,234.56 |
| `$#,##0.00` | $1,234.56 |
| `#,##0` | 1,235 |
| `#,##0.## 'Gems'` | 1,234.56 Gems |

For control over decimals, a number pattern works instead: `0` always shows a digit, `#` shows one only when needed, `,` groups thousands and `.` is the decimal point. Text is wrapped in single quotes. A pattern that cannot be read is refused by the editor.

### Currency Symbols

> **Info:**
Currency symbols are set in config.yml and have no editor option.

The short symbol shown next to buy and sell prices in the editor's item lists, one per currency. The key is the currency's id, and a currency with no entry shows its display name instead.

```yaml
currency-symbols:
  money: "$"
  points: "Points"
  experience: "XP"
  levels: "Levels"
  votepoints: "Vote Points"
```

An ExcellentEconomy or PhoenixCurrencies currency is keyed by its id in that plugin, and a Placeholder or Item currency by its identifier. PlaceholderAPI placeholders in a symbol are filled in for the admin viewing the list.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/currencies

---

# 🏦 Economy Plugins

## Economy Plugins

These currencies hand the balance over to another plugin. The plugin has to be installed and enabled before its type can be picked, and a shop priced in one that goes missing stops opening until it is back.

<figure><img src="../../.gitbook/assets/economy-plugins/economy-plugins.png" alt="" width="563"><figcaption><p>Edit Shop (Currency)</p></figcaption></figure>

## Vault

The server's main money, through [Vault](https://www.spigotmc.org/resources/vault.34315/). Vault holds no money by itself, so an economy plugin such as EssentialsX has to be installed alongside it. New shops are priced in Vault.

Vault does not run on Folia. Install [VaultUnlocked](https://modrinth.com/plugin/vaultunlocked) in its place, with an economy plugin that supports Folia.

Prices are written in the economy plugin's own format. Decimal prices are rounded to the cent, up when a player pays and down when a player is paid.

## PlayerPoints

Points from [PlayerPoints](https://modrinth.com/plugin/playerpoints). Points are whole numbers, so a decimal price is rounded up when a player pays and down when a player is paid.

## VotingPlugin

Vote points from [VotingPlugin](https://www.spigotmc.org/resources/votingplugin.15358/). Like PlayerPoints, they are whole numbers only.

## ExcellentEconomy

Any currency set up in [ExcellentEconomy](https://www.spigotmc.org/resources/excellenteconomy.106334/). Right-click the currency option in the editor and click **Currency** to pick one from a searchable list of every ExcellentEconomy currency. In the shop file, the currency's ExcellentEconomy id is its identifier.

Whether decimals are allowed is decided by ExcellentEconomy per currency, and prices are written in that currency's own format. A currency without decimals is rounded like PlayerPoints.

> **Info:**
ExcellentEconomy balances are only read and changed for players who are online.

## PhoenixCurrencies

Any currency set up in PhoenixCurrencies. Right-click the currency option in the editor and click **Currency** to pick one from a searchable list of every PhoenixCurrencies currency. In the shop file, the currency's PhoenixCurrencies id is its identifier.

Prices are rounded to the number of decimals the currency is set to, up when a player pays and down when a player is paid, and written in that currency's own format. Balances are read and changed for offline players too.

An id already taken by a built-in or ExcellentEconomy currency, such as `money`, keeps pointing at that currency.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/currencies/economy-plugins

---

# ✨ Experience

## Experience

A built-in currency that needs no other plugin. It is paid in experience points by default, or in levels when levels are turned on. Paying never takes a player below 0. Prices are written as `10 XP` or `10 Levels`.

## Points or Levels

Right-click the currency button in the editor and turn on **Count In Levels** to charge and pay levels instead of experience points. In the shop file, `levels: true` on an `EXPERIENCE` block turns levels on.

```yaml
currency:
  type: EXPERIENCE
  levels: true
```

Each shop, category and item has its own block, so one shop can price in points and another in levels. Both are whole numbers: a decimal price is rounded up when a player pays and down when a player is paid.

> **Info:**
A level costs more experience the higher it is, so 5 levels are worth far more to a level 50 player than to a level 5 one. Points cost every player the same.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/currencies/experience-and-levels

---

# 💎 Item Currencies

## Item Currencies

An Item currency makes players pay with an item they carry, such as emeralds, a custom coin or a named token, instead of money. This is a Premium feature and needs no other plugin.

Each shop, category or item gets its own Item currency, so a shop can be priced in diamonds while one of its categories is priced in emeralds.

## Currency Item

Pick the Item type on the shop, category or item, right-click it, and drop the item players should pay with into the slot. Only one of it is stored, whatever the stack size. Right-click the slot to get a copy of the stored item.

Name, lore, enchantments and custom data are kept, so a renamed paper can be a voucher that plain paper does not count as.

The same screen changes the stored item's name and lore without dropping it in again. MiniMessage, `&` codes and hex colours all work.

## Paying and Being Paid

Items are whole numbers, so a decimal price is rounded up when a player pays and down when a player is paid. Paying takes matching items from anywhere in the inventory. Being paid puts the items into the inventory, and anything that does not fit is dropped at the player's feet.

Prices are written as the amount followed by the item's name, such as `12 Emerald`. The item's own name is used with its colours. Set **Currency Display** on the same screen to write a different name instead, such as `&fDiamond Sword` for an item named `&c&lDIAMOND SWORD`. Item prices are whole numbers, so this type has no Currency Format.

## In the Shop File

```yaml
currency:
  type: ITEM
  identifier: item_shop
  item:
    display-name: Emerald
    material: EMERALD
    item-data: ''
    match: EXACT
```

| Option | Description |
| --- | --- |
| display-name | The Currency Display: the name written after prices. Empty uses the item's own name, colours included. |
| material | The item, when it has nothing special on it. |
| item-data | The full item, written by the editor when the item has a name, lore or other data. It wins over the material. |
| match | How closely a carried item has to match. See below. |

| Match | What counts |
| --- | --- |
| EXACT | Only an identical item: same name, lore, enchantments and data. The default. |
| MATERIAL\_AND\_NAME | The same material with the same display name. |
| MATERIAL | Any item of the same material. |

> **Warning:**
Loosen the match only for plain items. With MATERIAL, a renamed voucher and an ordinary copy of the same material pay the same.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/currencies/item-currencies

---

# 🏷️ Placeholder Currencies

## Placeholder Currencies

A Placeholder currency lets a shop charge in anything another plugin keeps a number for, such as a DeluxeMenus meta value or a token plugin with no economy hook of its own. The balance is read from a placeholder, and the money is moved by console commands you write. This is a Premium feature and needs [PlaceholderAPI](https://modrinth.com/plugin/placeholderapi).

<figure><img src="../../.gitbook/assets/placeholder-currencies/placeholder-currencies.png" alt="" width="563"><figcaption><p>Currencies (Souls)</p></figcaption></figure>

On Lite, Placeholder currencies are not loaded and the console says so once.

## Creating One

Open **Editor > Settings > Currencies** and click **New Placeholder Currency**, or pick the Placeholder type on a shop, category or item and right-click it. Each new currency gets the next free id, `custom_1`, `custom_2` and so on, with Tokens as its display name, and opens straight into its settings. Any number can be made, and each one shows up by its display name in the currency picker of a shop, category or item.

<figure><img src="../../.gitbook/assets/placeholder-currencies/creating-one.png" alt="" width="563"><figcaption><p>Currencies (New Placeholder Currency)</p></figcaption></figure>

Right-clicking a placeholder currency in the currency picker of a shop, category or item opens its settings, with the Currency Format beside them. The Currency Format is how prices are written, such as `%amount% Tokens`.

## Display Name

The name shown after prices, like 50 Tokens, and in the currency picker. It cannot be empty.

<figure><img src="../../.gitbook/assets/placeholder-currencies/display-name.png" alt="" width="563"><figcaption><p>Placeholder Currency (Display Name)</p></figcaption></figure>

## Balance Placeholder

The placeholder that holds a player's balance, such as `%deluxemenus_meta_mynewint_INTEGER_1%`. It has to return a number. Commas are ignored and `k`, `m`, `b` and `t` suffixes are read, but anything else that is not a number leaves the player unable to afford anything.

<figure><img src="../../.gitbook/assets/placeholder-currencies/balance-placeholder.png" alt="" width="563"><figcaption><p>Placeholder Currency (Balance Placeholder)</p></figcaption></figure>

An empty or wrong placeholder is not checked: the currency stays usable while PlaceholderAPI is installed, and every player reads as having nothing.

## Buy Command

The console command that runs when a player pays in this currency, taking the price from them. For example `dm meta %player% subtract mynewint INTEGER %amount_int%`.

<figure><img src="../../.gitbook/assets/placeholder-currencies/buy-command.png" alt="" width="563"><figcaption><p>Placeholder Currency (Buy Command)</p></figcaption></figure>

## Sell Command

The console command that runs when a player is paid in this currency, giving them the price. For example `dm meta %player% add mynewint INTEGER %amount_int%`.

<figure><img src="../../.gitbook/assets/placeholder-currencies/sell-command.png" alt="" width="563"><figcaption><p>Placeholder Currency (Sell Command)</p></figcaption></figure>

| Placeholder | Description |
| --- | --- |
| %player% | The player's name. |
| %amount% | The price, with decimals. |
| %amount\_int% | The price rounded up to a whole number. |

> **Warning:**
The plugin cannot tell whether a command worked. Test both commands on yourself before pricing a shop in the currency, since a typo takes nothing or pays nothing while the purchase or sale still goes through.

## In the Shop File

The whole currency is written into the block of the shop, category or item that uses it.

```yaml
currency:
  type: PLACEHOLDER
  identifier: tokens
  placeholder:
    display-name: Tokens
    balance: '%deluxemenus_meta_mynewint_INTEGER_1%'
    buy: 'dm meta %player% subtract mynewint INTEGER %amount_int%'
    sell: 'dm meta %player% add mynewint INTEGER %amount_int%'
```

When several blocks share an identifier, the first one read defines the currency. Editing it in-game rewrites every block that uses it.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/currencies/placeholder-currencies

---

# 🔣 Symbols and Formats

## How Prices Are Written

Every currency writes prices its own way. Vault, ExcellentEconomy and PhoenixCurrencies use the economy plugin's format, PlayerPoints writes `20 PlayerPoints`, VotingPlugin `20 Vote Tokens`, Experience `10 XP` or `5 Levels`, and Placeholder and Item currencies add their display name. A shop can replace this with a format of its own.

## Currency Format

How prices in one shop are written, set by right-clicking the shop's Currency option. Write `%amount%` where the number goes, and anything around it is shown as typed, so `%amount% PlayerPoints` writes `20 PlayerPoints` and `$%amount%` writes `$20`. Leave it empty to keep the currency's own format.

Write `%amount_short%` instead for a shortened number with a `k`, `m`, `b` or `t` suffix, so `$%amount_short%` writes `$1.5k` for 1500 and `$2.3m` for 2300000. Amounts under 1000 are written in full.

The format replaces the currency's own format completely, so put any symbol or name you want shown into it.

| Format | 1234.56 is written as |
| --- | --- |
| `%amount% PlayerPoints` | 1,234.56 PlayerPoints |
| `$%amount%` | $1,234.56 |
| `$%amount_short%` | $1.2k |
| `#,##0.00` | 1,234.56 |
| `$#,##0.00` | $1,234.56 |
| `#,##0` | 1,235 |
| `#,##0.## 'Gems'` | 1,234.56 Gems |

For control over decimals, a number pattern works instead: `0` always shows a digit, `#` shows one only when needed, `,` groups thousands and `.` is the decimal point. Text is wrapped in single quotes. A pattern that cannot be read is refused by the editor.

## Currency Symbols

> **Info:**
Currency symbols are set in config.yml and have no editor option.

The short symbol shown next to buy and sell prices in the editor's item lists, one per currency. The key is the currency's id, and a currency with no entry shows its display name instead.

```yaml
currency-symbols:
  money: "$"
  points: "Points"
  experience: "XP"
  levels: "Levels"
  votepoints: "Vote Points"
```

An ExcellentEconomy or PhoenixCurrencies currency is keyed by its id in that plugin, and a Placeholder or Item currency by its identifier. PlaceholderAPI placeholders in a symbol are filled in for the admin viewing the list.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/currencies/symbols-and-formats

---

# 📦 Items

> **Info:**
Items are saved in their category's file, under its list of items.

## Add an Item

Left-click the lime stained glass in **Editor > Shops > Shop > Category > Items** to create an item. It gets the next free `item_<number>` identifier and its editor opens straight away.

<figure><img src="../../.gitbook/assets/items/items.png" alt="" width="563"><figcaption><p>Edit Category (Items)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/items/add-an-item.png" alt="" width="563"><figcaption><p>Items (New Item)</p></figcaption></figure>

Pick an item up onto your cursor first and click the glass with it to add that exact item, name, lore, enchantments and custom data included. The stack's size becomes the item's amount, and the item is taken from your cursor. Clicking with an empty cursor creates an item with iron bars as a placeholder, to be replaced from its [display item](edit-item.md#display-item).

> **Info:**
An item added from your cursor is also added as its first [purchase item](#purchase-items), and chat tells you so. That is what a buyer receives and what a seller has to hand in, so later changes to the display item's name or lore do not change it.

## Add Multiple Items

Shift + left-click the lime stained glass to add many items at once. Put the items in the top five rows and press **Add Items**: every stack becomes its own item, added exactly as if you had clicked the glass with it on your cursor. Cancel, or closing the menu, gives the items back. This is a Premium feature.

## Items List

Every item in the list is shown as its display item, with its lore, then its buy price and sell price in the currency it uses, and the amount one purchase gives. A price of 0 is left off, and a spawner shows the mob it spawns. Left-click an item to edit it, right-click it to delete it after a confirmation.

<figure><img src="../../.gitbook/assets/items/items-list.png" alt="" width="563"><figcaption><p>Items (Grass Block)</p></figcaption></figure>

The order of the list is the order players see in the category's menu.

## Reordering

Turn Reordering on, click the item you want to move, then click the item it should swap places with. The New Item slot is hidden while reordering is on.

<figure><img src="../../.gitbook/assets/items/reordering.png" alt="" width="563"><figcaption><p>Items (Reordering)</p></figcaption></figure>

## Display Item

The display item is what players see in the category's menu. When the item has no [purchase items](#purchase-items) and no [purchase commands](#purchase-and-sell-commands), it is also what a purchase gives.

Drop an item on the slot to replace the display item. The dropped item's name, lore and data are taken as they are, and any name, lore or property set in the editor before is cleared. If the item had no purchase items yet, the dropped item is also added as the first one.

<figure><img src="../../.gitbook/assets/display-item/display-item.png" alt="" width="563"><figcaption><p>Display Item</p></figcaption></figure>

### Display Name

The name the item carries in the shop. Color codes are supported. Left empty, the item keeps its own name.

<figure><img src="../../.gitbook/assets/display-item/display-name.png" alt="" width="563"><figcaption><p>Display Item (Display Name)</p></figcaption></figure>

### Display Lore

The lore shown under the name. Color codes are supported. Left empty, the item keeps its own lore.

<figure><img src="../../.gitbook/assets/display-item/display-lore.png" alt="" width="563"><figcaption><p>Display Item (Display Lore)</p></figcaption></figure>

### Amount

How many are in the display item, from 1 to 64. It is also the size of one lot: selling one lot takes this many matching items from the player,. The display item itself is never given; set [purchase items](#purchase-items) for that.

<figure><img src="../../.gitbook/assets/display-item/amount.png" alt="" width="563"><figcaption><p>Display Item (Amount)</p></figcaption></figure>

### Item Properties

RGB color, item flags, banner patterns, enchantments, custom model data or item model, tooltip style, enchantment glint, potion effects, armor trim and spawner type. They have their own page: [Item Properties](item-properties.md).

<figure><img src="../../.gitbook/assets/display-item/item-properties.png" alt="" width="563"><figcaption><p>Display Item (Item Properties)</p></figcaption></figure>

## Purchase Items

### What a Purchase Gives

Purchase items are the real items a player receives when buying this entry. The display item is only what the shop shows, and is never given. An entry can hold as many as you want, and every one of them is given on each purchase.

<figure><img src="../../.gitbook/assets/purchase-items/purchase-items.png" alt="" width="563"><figcaption><p>Edit Item (Purchase Items)</p></figcaption></figure>

| Purchase items | Purchase commands | A purchase gives |
| --- | --- | --- |
| Set | Any | Every purchase item, then runs the commands. |
| Empty | Set | Nothing but the commands. |
| Empty | Empty | Nothing. The entry cannot be bought, and the editor warns on the Purchase Items option. |

Buying several at once multiplies each purchase item's amount by how many were bought. The player needs room for all of them, or the purchase is refused and nothing is taken.

### Add a Purchase Item

Click an item in your own inventory to pick it up, which turns the list green, then click anywhere in the list to add it. The item is taken from your cursor, exactly as it is, enchantments and custom data included.

<figure><img src="../../.gitbook/assets/purchase-items/add-an-item.png" alt="" width="563"><figcaption><p>Purchase Items (Add Item)</p></figcaption></figure>

Every purchase item in the list shows its lore and amount. Left-click one to edit it, right-click it to receive a copy.

### Edit a Purchase Item

Each purchase item has its own display name, lore, amount and [item properties](item-properties.md), separate from the display item's.

<figure><img src="../../.gitbook/assets/purchase-items/edit-a-purchase-item.png" alt="" width="563"><figcaption><p>Purchase Items (Grass Block)</p></figcaption></figure>

#### Purchase Item

Drop an item on the slot to replace this purchase item, keeping its amount. Right-click it to receive a copy.

<figure><img src="../../.gitbook/assets/purchase-items/purchase-item.png" alt="" width="563"><figcaption><p>Purchase Item</p></figcaption></figure>

#### Display Name & Display Lore

The name and lore the given item carries. Left empty, the item keeps its own.

<figure><img src="../../.gitbook/assets/purchase-items/display-name.png" alt="" width="563"><figcaption><p>Purchase Item (Display Name)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/purchase-items/display-lore.png" alt="" width="563"><figcaption><p>Purchase Item (Display Lore)</p></figcaption></figure>

#### Purchase Item Amount

How many of this item one purchase gives, from 1 to 64.

<figure><img src="../../.gitbook/assets/purchase-items/amount.png" alt="" width="563"><figcaption><p>Purchase Item (Amount)</p></figcaption></figure>

#### Remove

Removes this purchase item from the entry and hands it back to you.

<figure><img src="../../.gitbook/assets/purchase-items/remove.png" alt="" width="563"><figcaption><p>Purchase Item (Remove)</p></figcaption></figure>

### Selling

A player sells this entry by handing in items that match its **Sell Item**, set from the item editor. Without a sell item, they have to match the display item. How close the match has to be is the item's [Selling Rule](edit-item.md#selling-rule).

<figure><img src="../../.gitbook/assets/purchase-items/selling.png" alt="" width="563"><figcaption><p>Edit Item (Sell Item)</p></figcaption></figure>

One sale takes the sell item's amount of matching items and pays the sell price once, so an entry can sell a block of diamonds but buy back single diamonds. Without a sell item, one sale takes the display item's [amount](#amount).

In the item editor, drop an item on the Sell Item slot to set it, left-click it to edit its name, lore, amount and properties, and right-click it to get a copy. Its Remove button clears it, so the display item is matched again.

## Purchase and Sell Commands

### Purchase Commands

Commands run when a player buys this entry, after the [purchase items](#purchase-items) are given. An entry with purchase commands and no purchase items gives no items at all, which is how a rank, a kit from another plugin or a balance is sold.

<figure><img src="../../.gitbook/assets/purchase-and-sell-commands/purchase-commands.png" alt="" width="563"><figcaption><p>Edit Item (Purchase Commands)</p></figcaption></figure>

### Sell Commands

Commands run when a player sells this entry, after they are paid.

<figure><img src="../../.gitbook/assets/purchase-and-sell-commands/sell-commands.png" alt="" width="563"><figcaption><p>Edit Item (Sell Commands)</p></figcaption></figure>

### Add a Command

Left-click the lime stained glass and type the command, without the slash. A dialog box asks for it, and on server versions that don't support dialogs it falls back to the chat. Left-click a command in the list to remove it.

<figure><img src="../../.gitbook/assets/purchase-and-sell-commands/add-a-command.png" alt="" width="563"><figcaption><p>Purchase Commands (Add Command)</p></figcaption></figure>

Commands run from the console. Start one with `*` to run it as the player instead, such as `*spawn`.

### Placeholders

| Placeholder | Description |
| --- | --- |
| `%player%` | The name of the player. |
| `%uuid%` | The UUID of the player. |
| `%amount%` | How many times the entry was bought or sold in this transaction. |
| `%item%` | The name of the display item. |
| `%price%` | The total price of the transaction. |
| `%currency%` | The name of the currency. |
| `%shop%` | The display name of the shop. |

PlaceholderAPI placeholders work too when PlaceholderAPI is installed.

> **Info:**
Each command runs once per transaction, however many were bought or sold at once. `%amount%` counts those purchases, not items: buying 3 of an entry whose display amount is 16 fills in `3`.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items

---

# 🖼️ Display Item

The display item is what players see in the category's menu. When the item has no [purchase items](purchase-items.md) and no [purchase commands](purchase-and-sell-commands.md), it is also what a purchase gives.

## Display Item

Drop an item on the slot to replace the display item. The dropped item's name, lore and data are taken as they are, and any name, lore or property set in the editor before is cleared. If the item had no purchase items yet, the dropped item is also added as the first one.

<figure><img src="../../.gitbook/assets/display-item/display-item.png" alt="" width="563"><figcaption><p>Display Item</p></figcaption></figure>

## Display Name

The name the item carries in the shop. Color codes are supported. Left empty, the item keeps its own name.

<figure><img src="../../.gitbook/assets/display-item/display-name.png" alt="" width="563"><figcaption><p>Display Item (Display Name)</p></figcaption></figure>

## Display Lore

The lore shown under the name. Color codes are supported. Left empty, the item keeps its own lore.

<figure><img src="../../.gitbook/assets/display-item/display-lore.png" alt="" width="563"><figcaption><p>Display Item (Display Lore)</p></figcaption></figure>

## Amount

How many are in the display item, from 1 to 64. It is also the size of one lot: selling one lot takes this many matching items from the player,. The display item itself is never given; set [purchase items](purchase-items.md) for that.

<figure><img src="../../.gitbook/assets/display-item/amount.png" alt="" width="563"><figcaption><p>Display Item (Amount)</p></figcaption></figure>

## Item Properties

RGB color, item flags, banner patterns, enchantments, custom model data or item model, tooltip style, enchantment glint, potion effects, armor trim and spawner type. They have their own page: [Item Properties](item-properties.md).

<figure><img src="../../.gitbook/assets/display-item/item-properties.png" alt="" width="563"><figcaption><p>Display Item (Item Properties)</p></figcaption></figure>

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items/display-item

---

# ✏️ Edit Item

> **Info:**
Every option on this page is saved to the item's entry in its category's file.

## Display Item

The item that represents this entry in the shop. Left-click it to edit its name, lore, amount and properties on [Display Item](README.md#display-item). Right-click it to receive a copy.

<figure><img src="../../.gitbook/assets/items/display-item.png" alt="" width="563"><figcaption><p>Edit Item (Display Item)</p></figcaption></figure>

Drop an item on the slot to replace it. The dropped item's name, lore and data are taken as they are, and any name, lore or property set in the editor before is cleared. If the item had no [purchase items](README.md#purchase-items) yet, the dropped item is also added as the first one.

## Purchase Items

The items a purchase gives, and the item a sale has to match. See [Purchase Items](README.md#purchase-items).

<figure><img src="../../.gitbook/assets/items/purchase-items.png" alt="" width="563"><figcaption><p>Edit Item (Purchase Items)</p></figcaption></figure>

## Purchase Commands & Sell Commands

Commands run when a player buys or sells this entry. See [Purchase & Sell Commands](README.md#purchase-and-sell-commands).

<figure><img src="../../.gitbook/assets/items/purchase-commands.png" alt="" width="563"><figcaption><p>Edit Item (Purchase Commands)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/items/sell-commands.png" alt="" width="563"><figcaption><p>Edit Item (Sell Commands)</p></figcaption></figure>

## Buy Price

What a player pays for one purchase of this entry, whatever amount it gives. Short forms such as `1.5k` or `2m` are accepted. A price of 0 means the item cannot be bought, unless Free is on.

<figure><img src="../../.gitbook/assets/items/buy-price.png" alt="" width="563"><figcaption><p>Edit Item (Buy Price)</p></figcaption></figure>

## Sell Price

What a player is paid for selling one lot of this entry, a lot being the display item's amount. A price of 0 means the item cannot be sold.

<figure><img src="../../.gitbook/assets/items/sell-price.png" alt="" width="563"><figcaption><p>Edit Item (Sell Price)</p></figcaption></figure>

## Currency

Prices this item in another currency than its category's or its shop's. Left-click swaps between the currency types, starting at the inherited one, and right-click opens the chosen type to pick the currency. The types are listed on [Currencies](../currencies/).

<figure><img src="../../.gitbook/assets/items/currency.png" alt="" width="563"><figcaption><p>Edit Item (Currency)</p></figcaption></figure>

If the chosen currency's plugin is not installed, the item is hidden from the shop until it is.

> **Info:**
This feature is only available with the Premium Plan.

## Selling Rule

How close a player's item has to be to this entry before the shop buys it back. The item it is compared against is described on [Purchase Items](README.md#selling).

<figure><img src="../../.gitbook/assets/items/selling-rule.png" alt="" width="563"><figcaption><p>Edit Item (Selling Rule)</p></figcaption></figure>

| Rule | What has to match |
| --- | --- |
| Exact | Everything: material, name, lore, enchantments and custom data. |
| Material And Name | The material and the display name. |
| Material | Only the material. |

> **Warning:**
Anything looser than Exact lets a player buy something cheap, change it, and sell it back as this entry. Keep Exact unless the sell price is low enough not to matter.

## Sell Item

What a player hands in when selling this entry, and how many one sale takes. Drop an item on the slot to set it, left-click to edit it and right-click to get a copy. Without one, sales match the display item. See [Selling](README.md#selling).

<figure><img src="../../.gitbook/assets/items/sell-item.png" alt="" width="563"><figcaption><p>Edit Item (Sell Item)</p></figcaption></figure>

## Max Per Purchase

The most lots one purchase can buy. `-1` means no limit. A bigger purchase is refused with a message naming the cap in items. The buy menu's add and Fill Inventory buttons stop at the cap, the bulk buy menu offers nothing above it, and a `BUY_STACK` click buys no more than it.

<figure><img src="../../.gitbook/assets/items/max-per-purchase.png" alt="" width="563"><figcaption><p>Edit Item (Max Per Purchase)</p></figcaption></figure>

## Minimum Sale

The fewest items one sale has to contain, rounded up to whole lots. `-1` means no minimum. A smaller sale is refused. The sell menu starts at the minimum and cannot go below it, the bulk sell menu hides the options under it, and a `SELL_ONE` click sells the minimum. `/sell`, AutoSell and the Bedrock sell form skip the item while the player carries fewer.

<figure><img src="../../.gitbook/assets/items/minimum-sale.png" alt="" width="563"><figcaption><p>Edit Item (Minimum Sale)</p></figcaption></figure>

## Stock

Limits how many of this item are for sale and how many one player may buy, with a restock rule to bring it back. It has its own page: [Stock & Restock](stock-and-restock.md).

<figure><img src="../../.gitbook/assets/items/stock.png" alt="" width="563"><figcaption><p>Edit Item (Stock)</p></figcaption></figure>

> **Info:**
This feature is only available with the Premium Plan.

## Requirements

Checks a purchase or a sale has to pass, such as a permission, a world or a placeholder value. It has its own page: [Requirements](requirements.md).

<figure><img src="../../.gitbook/assets/items/requirements.png" alt="" width="563"><figcaption><p>Edit Item (Requirements)</p></figcaption></figure>

> **Info:**
This feature is only available with the Premium Plan.

## Extra

The options most entries never need, on a screen of their own.

<figure><img src="../../.gitbook/assets/items/extra.png" alt="" width="563"><figcaption><p>Edit Item (Extra)</p></figcaption></figure>

### Free

Lets players buy this entry without paying, whatever the buy price says. Prices show as Free everywhere. Stock, player limits, requirements, max per purchase and purchase commands still apply, and the sell price is untouched.

<figure><img src="../../.gitbook/assets/items/free.png" alt="" width="563"><figcaption><p>Extra (Free)</p></figcaption></figure>

> **Warning:**
A free item with a sell price can be bought for nothing and sold for money. The money loop audit flags it, unless stock or a player limit caps it.

### Sell Damaged

Lets worn tools and armour be sold to this entry. They are paid by the durability they have left, so a tool at 40% durability sells for 40% of the price, and Damaged Minimum sets the lowest share they ever pay. When it is off, a worn item only sells with the Material selling rule, at full price.

<figure><img src="../../.gitbook/assets/items/sell-damaged.png" alt="" width="563"><figcaption><p>Extra (Sell Damaged)</p></figcaption></figure>

### Messages

Buy Message, Sell Message and Cannot Afford Message replace the normal message for this entry only. They take `%amount%`, `%item%`, `%price%`, `%currency%` and `%balance%`. Empty falls back to the category's message, then the normal one.

<figure><img src="../../.gitbook/assets/items/messages.png" alt="" width="563"><figcaption><p>Extra (Buy Message)</p></figcaption></figure>

## Enabled

A disabled item stays configured in the category but is hidden from the shop, and cannot be bought or sold.

<figure><img src="../../.gitbook/assets/items/enabled.png" alt="" width="563"><figcaption><p>Edit Item (Enabled)</p></figcaption></figure>

## Identifier

The unique id of this item inside its category. New items get a generated one.

<figure><img src="../../.gitbook/assets/items/identifier.png" alt="" width="563"><figcaption><p>Edit Item (Identifier)</p></figcaption></figure>

> **Danger:**
Stock counts and Sign Shops point at the identifier. Changing it starts the item's stock over and unlinks any Sign Shop that uses it.

## Delete

Deletes the item from its category, after a confirmation.

<figure><img src="../../.gitbook/assets/items/delete.png" alt="" width="563"><figcaption><p>Edit Item (Delete)</p></figcaption></figure>

> **Danger:**
This option is permanent, and items can't be restored.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items/edit-item

---

# 🎨 Item Properties

Item Properties fine-tune an item beyond its name and lore. The same menu is opened from the [display item](README.md#display-item) and from every [purchase item](README.md#purchase-items), and each keeps its own properties. An option that does not fit the item's material shows an error in its lore and has no effect.

## RGB Color

The color of leather armor, potions, tipped arrows, firework stars and filled maps, written as `R, G, B` with each number from 0 to 255, such as `255, 0, 128`. Right-click clears it.

<figure><img src="../../.gitbook/assets/item-properties/rgb-color.png" alt="" width="563"><figcaption><p>Item Properties (RGB Color)</p></figcaption></figure>

## Item Flags

Hides parts of the item's tooltip, such as enchantments or attributes. Pick a flag from the list to add it, and pick it again to remove it. The flags currently set are listed on the option.

<figure><img src="../../.gitbook/assets/item-properties/item-flags.png" alt="" width="563"><figcaption><p>Item Properties (Add Item Flag)</p></figcaption></figure>

## Banner Patterns

The patterns of a banner or a shield, one per line as `COLOR;PATTERN_TYPE`, such as `RED;STRIPE_TOP`. They are applied in the order listed.

<figure><img src="../../.gitbook/assets/item-properties/banner-patterns.png" alt="" width="563"><figcaption><p>Item Properties (Banner Patterns)</p></figcaption></figure>

## Enchantments

One enchantment per line as `ENCHANTMENT:LEVEL`, such as `UNBREAKING:3`. Without a level, level 1 is used. Enchantments from other plugins work as long as the server knows their name. One that cannot be found is left off, and the console lists it.

<figure><img src="../../.gitbook/assets/item-properties/enchantments.png" alt="" width="563"><figcaption><p>Item Properties (Enchantments)</p></figcaption></figure>

## Custom Model Data / Item Model

A number sets the Custom Model Data. On server versions with item models, a `namespace:key` sets the Item Model instead. Only one of the two is kept. Right-click clears it.

<figure><img src="../../.gitbook/assets/item-properties/custom-model-data-item-model.png" alt="" width="563"><figcaption><p>Item Properties (Custom Model Data / Item Model)</p></figcaption></figure>

## Tooltip Style

The tooltip style of the item as a `namespace:key`. Right-click clears it. It needs a server version with tooltip styles.

<figure><img src="../../.gitbook/assets/item-properties/tooltip-style.png" alt="" width="563"><figcaption><p>Item Properties (Tooltip Style)</p></figcaption></figure>

## Enchantment Glint

Forces the enchantment glow on, with no enchantment needed. It needs a server version with the glint override.

<figure><img src="../../.gitbook/assets/item-properties/enchantment-glint.png" alt="" width="563"><figcaption><p>Item Properties (Enchantment Glint)</p></figcaption></figure>

## Potion Effects

The effects of a potion or a tipped arrow, one per line as `type;duration;amplifier`, with the duration in ticks, such as `speed;200;0`.

<figure><img src="../../.gitbook/assets/item-properties/potion-effects.png" alt="" width="563"><figcaption><p>Item Properties (Potion Effects)</p></figcaption></figure>

## Spawner Type

The mob a spawner spawns, picked from a list of every mob with a spawn egg. Right-click clears it and leaves a plain spawner.

<figure><img src="../../.gitbook/assets/item-properties/spawner-type.png" alt="" width="563"><figcaption><p>Item Properties (Spawner Type)</p></figcaption></figure>

## Trim Material & Trim Pattern

The armor trim of a helmet, chestplate, leggings or boots. The trim only shows once both the material and the pattern are set. Right-click clears either one.

<figure><img src="../../.gitbook/assets/item-properties/trim-material.png" alt="" width="563"><figcaption><p>Item Properties (Trim Material)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/item-properties/trim-pattern.png" alt="" width="563"><figcaption><p>Item Properties (Trim Pattern)</p></figcaption></figure>

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items/item-properties

---

# ⌨️ Purchase & Sell Commands

## Purchase Commands

Commands run when a player buys this entry, after the [purchase items](purchase-items.md) are given. An entry with purchase commands and no purchase items gives no items at all, which is how a rank, a kit from another plugin or a balance is sold.

<figure><img src="../../.gitbook/assets/purchase-and-sell-commands/purchase-commands.png" alt="" width="563"><figcaption><p>Edit Item (Purchase Commands)</p></figcaption></figure>

## Sell Commands

Commands run when a player sells this entry, after they are paid.

<figure><img src="../../.gitbook/assets/purchase-and-sell-commands/sell-commands.png" alt="" width="563"><figcaption><p>Edit Item (Sell Commands)</p></figcaption></figure>

## Add a Command

Left-click the lime stained glass and type the command, without the slash. A dialog box asks for it, and on server versions that don't support dialogs it falls back to the chat. Left-click a command in the list to remove it.

<figure><img src="../../.gitbook/assets/purchase-and-sell-commands/add-a-command.png" alt="" width="563"><figcaption><p>Purchase Commands (Add Command)</p></figcaption></figure>

Commands run from the console. Start one with `*` to run it as the player instead, such as `*spawn`.

## Placeholders

| Placeholder | Description |
| --- | --- |
| `%player%` | The name of the player. |
| `%uuid%` | The UUID of the player. |
| `%amount%` | How many times the entry was bought or sold in this transaction. |
| `%item%` | The name of the display item. |
| `%price%` | The total price of the transaction. |
| `%currency%` | The name of the currency. |
| `%shop%` | The display name of the shop. |

PlaceholderAPI placeholders work too when PlaceholderAPI is installed.

> **Info:**
Each command runs once per transaction, however many were bought or sold at once. `%amount%` counts those purchases, not items: buying 3 of an entry whose display amount is 16 fills in `3`.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items/purchase-and-sell-commands

---

# 🎒 Purchase Items

## What a Purchase Gives

Purchase items are the real items a player receives when buying this entry. The display item is only what the shop shows, and is never given. An entry can hold as many as you want, and every one of them is given on each purchase.

<figure><img src="../../.gitbook/assets/purchase-items/purchase-items.png" alt="" width="563"><figcaption><p>Edit Item (Purchase Items)</p></figcaption></figure>

| Purchase items | Purchase commands | A purchase gives |
| --- | --- | --- |
| Set | Any | Every purchase item, then runs the commands. |
| Empty | Set | Nothing but the commands. |
| Empty | Empty | Nothing. The entry cannot be bought, and the editor warns on the Purchase Items option. |

Buying several at once multiplies each purchase item's amount by how many were bought. The player needs room for all of them, or the purchase is refused and nothing is taken.

## Add an Item

Click an item in your own inventory to pick it up, which turns the list green, then click anywhere in the list to add it. The item is taken from your cursor, exactly as it is, enchantments and custom data included.

<figure><img src="../../.gitbook/assets/purchase-items/add-an-item.png" alt="" width="563"><figcaption><p>Purchase Items (Add Item)</p></figcaption></figure>

Every purchase item in the list shows its lore and amount. Left-click one to edit it, right-click it to receive a copy.

## Edit a Purchase Item

Each purchase item has its own display name, lore, amount and [item properties](item-properties.md), separate from the display item's.

<figure><img src="../../.gitbook/assets/purchase-items/edit-a-purchase-item.png" alt="" width="563"><figcaption><p>Purchase Items (Grass Block)</p></figcaption></figure>

### Purchase Item

Drop an item on the slot to replace this purchase item, keeping its amount. Right-click it to receive a copy.

<figure><img src="../../.gitbook/assets/purchase-items/purchase-item.png" alt="" width="563"><figcaption><p>Purchase Item</p></figcaption></figure>

### Display Name & Display Lore

The name and lore the given item carries. Left empty, the item keeps its own.

<figure><img src="../../.gitbook/assets/purchase-items/display-name.png" alt="" width="563"><figcaption><p>Purchase Item (Display Name)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/purchase-items/display-lore.png" alt="" width="563"><figcaption><p>Purchase Item (Display Lore)</p></figcaption></figure>

### Amount

How many of this item one purchase gives, from 1 to 64.

<figure><img src="../../.gitbook/assets/purchase-items/amount.png" alt="" width="563"><figcaption><p>Purchase Item (Amount)</p></figcaption></figure>

### Remove

Removes this purchase item from the entry and hands it back to you.

<figure><img src="../../.gitbook/assets/purchase-items/remove.png" alt="" width="563"><figcaption><p>Purchase Item (Remove)</p></figcaption></figure>

## Selling

A player sells this entry by handing in items that match its **Sell Item**, set from the item editor. Without a sell item, they have to match the display item. How close the match has to be is the item's [Selling Rule](edit-item.md#selling-rule).

<figure><img src="../../.gitbook/assets/purchase-items/selling.png" alt="" width="563"><figcaption><p>Edit Item (Sell Item)</p></figcaption></figure>

One sale takes the sell item's amount of matching items and pays the sell price once, so an entry can sell a block of diamonds but buy back single diamonds. Without a sell item, one sale takes the display item's [amount](display-item.md#amount).

In the item editor, drop an item on the Sell Item slot to set it, left-click it to edit its name, lore, amount and properties, and right-click it to get a copy. Its Remove button clears it, so the display item is matched again.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items/purchase-items

---

# 🔒 Requirements

> **Info:**
This feature is only available with the Premium Plan.

Requirements are checks a purchase or a sale of this item has to pass before it goes through, such as a permission, a world or a placeholder value. They are read before the stock limits, so a player who does not meet them is refused before they are told the item is sold out.

## Add a Requirement

Left-click the lime stained glass to add a check. It is named `check_<number>`, starts as a **permission** check, and its editor opens straight away. Every check in the list shows its type, what it checks and what it applies to. Left-click one to edit it, right-click it to delete it, together with its deny actions, after a confirmation.

<figure><img src="../../.gitbook/assets/requirements/requirements.png" alt="" width="563"><figcaption><p>Edit Item (Requirements)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/requirements/add-a-requirement.png" alt="" width="563"><figcaption><p>Requirements (New Requirement)</p></figcaption></figure>

## Minimum

How many of the checks have to pass. At 0 it shows **All Requirements**, and every check has to pass. Only the checks that apply to the transaction are counted, so a minimum higher than that number asks for all of them.

<figure><img src="../../.gitbook/assets/requirements/minimum.png" alt="" width="563"><figcaption><p>Requirements (Minimum)</p></figcaption></figure>

## Type

Which check this is. Only the fields the chosen type reads are shown.

<figure><img src="../../.gitbook/assets/requirements/type.png" alt="" width="563"><figcaption><p>Requirement (Type)</p></figcaption></figure>

| Type | Fields | Passes when |
| --- | --- | --- |
| permission | Permission | The player has the permission. |
| compare | Input, Operator, Output | Input compared to Output with the operator holds true. |
| world | World | The player is in that world, picked from the server's loaded worlds. |
| gamemode | Gamemode | The player is in that gamemode, picked from the list. |
| holding | Held Item, Item Name, Whole Inventory | The player holds that item in their main hand. Drop the item on the slot to set it; with none set, any held item passes. A custom item from ItemsAdder, Nexo, CraftEngine and the other supported plugins is saved by its id, such as `nexo:ruby_pickaxe`, and only that item passes. A plain material such as `DIAMOND_PICKAXE` does not count custom items built on it. With Item Name set, the item's name has to match it exactly, colors ignored. With Whole Inventory on, an item anywhere in the main inventory or hotbar counts, armor and off-hand excluded. |
| enchantment | Enchantment | The player holds an item in their main hand that can take the enchantment, picked from a filterable list of every vanilla enchantment. |
| platform | Platform | The player joined from that platform, Bedrock (through Floodgate or Geyser) or Java. |
| region | Region | The player stands inside that [WorldGuard](https://enginehub.org/worldguard) region. Only offered when WorldGuard is installed. |
| world-time | World Time | The time of day in the player's world is inside the range, both ends included, such as `08:00-14:45`. Tick 0 reads as 06:00, so `/time set noon` is 12:00 and `/time set midnight` is 00:00. A range such as `22:00-06:00` runs past midnight. |
| playtime | Playtime | The player has played at least that long on this server, such as `15m`, `12h` or `5d 12h`. Days, hours, minutes and seconds can be combined. |

## Operator

How a **compare** check weighs Input against Output. `>`, `>=`, `==`, `!=`, `<` and `<=` compare them as numbers. `equals`, `equals ignorecase`, `contains` and `not contains` compare them as text. Input and Output accept PlaceholderAPI placeholders, such as `%player_level%` against `30`.

## Negate

Flips the check, so it passes when it would fail. A negated **permission** check passes for players without the permission, and a negated **platform** check set to Bedrock passes for Java players.

<figure><img src="../../.gitbook/assets/requirements/negate.png" alt="" width="563"><figcaption><p>Requirement (Negate)</p></figcaption></figure>

> **Warning:**
A check that cannot be evaluated refuses the transaction, negated or not: a placeholder with PlaceholderAPI not installed, a number operator where either side is not a number, a gamemode or platform that does not exist, an unreadable time range or playtime, a region check with WorldGuard not installed, an unknown operator or an unknown type. The console says why, once per check.

## Applies To

Whether the check runs on buying, on selling, or on both, which is the default. A check that does not apply to a transaction is ignored for it, and does not count towards the [Minimum](#minimum).

<figure><img src="../../.gitbook/assets/requirements/applies-to.png" alt="" width="563"><figcaption><p>Requirement (Applies To)</p></figcaption></figure>

## Deny Actions

Actions run when this check fails and the transaction is refused, such as a message telling the player what they are missing, a sound or a title. When several checks fail, each one runs its own deny actions.

<figure><img src="../../.gitbook/assets/requirements/deny-actions.png" alt="" width="563"><figcaption><p>Requirement (Deny Actions)</p></figcaption></figure>

> **Info:**
A refused transaction sends no message of its own, only the shop's [deny actions](../shops/edit-shop.md#actions), a sound by default. Use deny actions to tell the player why.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items/requirements

---

# 📊 Stock & Restock

> **Info:**
This feature is only available with the Premium Plan.

Stock limits apply to buying only. Stock is counted in items, not purchases: an entry whose display amount is 16 with a stock of 64 sells out after 4 purchases. It is kept per shop, category and item identifier, so renaming any of them starts the count over.

## Stock

How many are for sale, shared by every player. `-1` means as many as they like. Selling the item back puts it back on the shelf, up to this number. Raising the stock in the editor adds the difference to what is left right away.

<figure><img src="../../.gitbook/assets/stock-and-restock/stock.png" alt="" width="563"><figcaption><p>Stock</p></figcaption></figure>

## Player Limit

How many one player may buy between two restocks. `-1` means as many as they like. A restock resets every player's count.

<figure><img src="../../.gitbook/assets/stock-and-restock/player-limit.png" alt="" width="563"><figcaption><p>Stock (Player Limit)</p></figcaption></figure>

On Premium, the [IP limit](../../configurations/settings-file.md#ip-limit) also caps how many accounts on one connection can buy the item between restocks, so alternate accounts cannot multiply a player's limit.

## Sell Limit

How many one player may sell between two restocks. `-1` means as many as they like. A restock resets every player's count, and `/sell` and AutoSell sell only up to what is left.

<figure><img src="../../.gitbook/assets/stock-and-restock/sell-limit.png" alt="" width="563"><figcaption><p>Stock (Sell Limit)</p></figcaption></figure>

## Limit Group

A name shared by several items of the same shop, such as `crate_keys`. Items with the same group share one count per player: buying any of them counts toward the player limit of all of them, and the same for selling. The limit checked is the one of the item being bought or sold. Case does not matter, and empty means no group.

<figure><img src="../../.gitbook/assets/stock-and-restock/limit-group.png" alt="" width="563"><figcaption><p>Stock (Limit Group)</p></figcaption></figure>

Stock stays per item. The [IP limit](../../configurations/settings-file.md#ip-limit) is counted per group too. A restock of any item in the group resets the whole group's counts.

With the Network add-on's shared stock, groups are not applied and each item keeps its own counts.

## Commands

| Command | Permission | Description |
| --- | --- | --- |
| `/pshop limits reset <player> [shop] [category] [item]` | phoenixshop.command.limits | Resets a player's buy and sell counts, for everything or only one shop, category or item. Works for offline players, by name or UUID. Resetting an item in a limit group resets the whole group. |
| `/pshop stock set <shop> <category> <item> <amount>` | phoenixshop.command.stock | Sets how many are left, between 0 and the item's stock. Only for items with a stock limit. |
| `/pshop stock restock <shop> <category> <item>` | phoenixshop.command.stock | Restocks the item now: full stock, and every player's counts for it, or its limit group, are reset. Posts the restock [webhook](../../features/discord-webhooks.md). |

`/pshop limits` is not available with the Network add-on's shared stock.

## Restock

When the item goes back to its full stock. Every restock also resets the player limits. Choose the mode first, then the fields that mode shows.

<figure><img src="../../.gitbook/assets/stock-and-restock/restock.png" alt="" width="563"><figcaption><p>Stock (Restock)</p></figcaption></figure>

| Mode | Fields | Comes back |
| --- | --- | --- |
| Never | None | Never on its own. |
| Interval | Days (0 to 365), Hours, Minutes | That long after it sold out. |
| Daily | Time | Every day at that time. |
| Weekly | Weekday, Time | Every week on that day at that time. |
| Monthly | Day of Month (1 to 28), Time | Every month on that day at that time. |

The Turn Off button sets the mode back to Never. Times use the server's clock. Time opens a time picker and Weekday a day picker, see [Date and Time Pickers](../categories/edit-category.md#date-and-time-pickers).

> **Warning:**
Interval only starts counting once the stock runs out. An item with a player limit and no stock limit never runs out, so its player limits only reset with a Daily, Weekly or Monthly restock.

The restock rule is written in the item's entry as a `restock` block, which can also be typed by hand:

| Key | Used by | Description |
| --- | --- | --- |
| `type` | all | `NEVER`, `INTERVAL`, `DAILY`, `WEEKLY` or `MONTHLY`. |
| `every` | `INTERVAL` | How long after it sells out, such as `30m`, `6h` or `1d12h`. Units are `s`, `m`, `h` and `d`. |
| `time` | `DAILY`, `WEEKLY`, `MONTHLY` | The time of day, such as `'04:00'`. |
| `day` | `WEEKLY`, `MONTHLY` | A weekday such as `MONDAY`, or a day of the month from `1` to `28`. |

```yml
restock:
  type: WEEKLY
  day: MONDAY
  time: '04:00'
```

An item with no `restock` block never restocks.

> **Info:**
A block that cannot be read is treated as `NEVER`.

## Availability

Limits when the item is for sale at all. Outside that time it is hidden from the shop, `/sell` and sign shops, and cannot be bought or sold. Leave a field empty to not use it. This feature is only available with the Premium Plan.

<figure><img src="../../.gitbook/assets/stock-and-restock/available-from.png" alt="" width="563"><figcaption><p>Stock (Available From)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/stock-and-restock/available-until.png" alt="" width="563"><figcaption><p>Stock (Available Until)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/stock-and-restock/sale-window.png" alt="" width="563"><figcaption><p>Stock (Sale Window)</p></figcaption></figure>

| Field | Description |
| --- | --- |
| Available From | The date and time it goes on sale, picked in the [date picker](../categories/edit-category.md#date-and-time-pickers). |
| Available Until | The date and time it stops being for sale. |
| Sale Window | How long it stays for sale after each restock, such as `2h`. Only used with a Daily, Weekly or Monthly restock, counting from the restock time. |

With a Daily restock at 18:00 and a 2h window, the item is for sale from 18:00 to 20:00 every day. Dates and times use the server's time zone.

```yaml
available:
  from: '2026-10-25 00:00'
  until: '2026-11-01 00:00'
  window: 2h
```

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/items/stock-and-restock

---

# 🏬 Player Shops

> **Info:**
Every player shop is stored in the database, SQLite or MySQL as set in config.yml. A player-shops.yml from an older version is moved into the database on the first start and renamed to player-shops.yml.migrated. Its settings are in the player-shops section of config.yml.

## Information

A player shop is a sign on a container that the player owns. The container is the stock: buyers take items out of it, sellers put items into it, and the money goes straight between the two players. The server never stands in the middle of a trade.

<figure><img src="../../.gitbook/assets/chest-shops/chest-shops.png" alt="" width="563"><figcaption><p>Editor (Chest Shops)</p></figcaption></figure>

On Lite each player can own up to 25 player shops, and [admin shops](#admin-shops) are capped at 25 across the server. Everything else on these pages works on Lite too.

## Create a Player Shop

Player shops are off until they are turned on with [Enabled](settings.md#enabled). Then hold the item to sell and Shift + Left-Click a chest, trapped chest, barrel or shulker box you can open. [Click Creation](settings.md#click-creation) changes that click. The shop is made straight away: a [sign](settings.md#sign-material) goes up on the side you clicked, or on another free side, the [Creation Cost](settings.md#creation-cost) is charged, and the shop sells one item per click to players.

The shop's editor opens straight away to pick the [mode](edit-player-shop.md#mode) and the prices. Its prices start at 0, so set them there before anyone trades; right-click the sign to come back to it later. See [Edit Player Shop](edit-player-shop.md).

A normal Left-Click breaks the container as usual. In creative mode the click no longer breaks the container when a shop is made from it.

An ender chest makes an ender chest shop. Its stock is the owner's own ender chest, so they can restock it from any ender chest in the world, and several ender chests can each carry a shop. The shop only trades while the owner is online, since an offline player's ender chest cannot be reached. Staff cannot restock it, because opening the ender chest shows them their own. An admin shop on an ender chest works like any other admin shop.

Nothing happens at all while player shops are turned off (except for admin shops on Lite), for a player without `phoenixshop.sign.create`, or on a container that already has a shop. Otherwise the player is told why no shop was made when:

* The world is one of the [Blocked Worlds](settings.md#blocked-worlds). A player with `phoenixshop.sign.bypass` can still make one.
* The item is on the [Blocked Items](settings.md#blocked-items) list.
* The item is a renamed lookalike of a real plugin item, or uses one of the [Protected Names](settings.md#protected-names). See [Fake Items](#fake-items).
* The player cannot open the container, for example because a lock plugin or a claim keeps them out.
* [Require Claim](settings.md#require-claim) is on and the container is not inside a claim the player can build in.
* The player already owns as many shops as their [limit](settings.md#max-per-player) allows.
* The player cannot pay the [Creation Cost](settings.md#creation-cost).
* The container has no free side for the sign, or the player is not allowed to build where it would go.

## Fake Items

A renamed item that does not come from a supported item plugin cannot be sold, bought or used as a payment when its name matches a real plugin item. Colors, case, accents, small caps and word order are ignored, and the real item's id counts as a name too, so a paper renamed **Vote Key** is refused because of the PhoenixCrates key `phoenixcrates:key:vote`, whatever that key is called on the server.

The real items it knows are every item of the installed item plugins: PhoenixCrates keys and crates, Nexo, ItemsAdder, MMOItems, MythicMobs, ExecutableItems, ExecutableBlocks, CraftEngine and Slimefun. The list is built a few seconds after startup and after `/pshop reload`, and again every 10 minutes. Head plugins are not checked. Add any other name to [Protected Names](settings.md#protected-names). Items that were only renamed, such as a sword called Bob's Sword, are still allowed. A shop that was set up with a fake item before stops trading.

## Admin Shops

An admin shop never runs out or fills up, pays and takes no one's money, and shows Admin Shop as its owner. A player with `phoenixshop.sign.admin` turns any shop into one with [Admin Shop](edit-player-shop.md#admin-shop) in its editor.

<figure><img src="../../.gitbook/assets/chest-shops/admin-shops.png" alt="" width="563"><figcaption><p>Chest Shops (Admin Shops)</p></figcaption></figure>

For a player with `phoenixshop.sign.admin` but not `phoenixshop.sign.create`, the left-click makes an admin shop straight away. It costs nothing and does not count towards the limit. Lite has no Admin Shop toggle, so this is the only way to make one there.

## Sign Text

The four lines are the owner's name in green, then the mode with the amount traded per click, the item, and the price, with buy prices in red and sell prices in green. The mode reads `Selling: 16`, `Buying: 32` or `Buy & Sell: 16`. A shop that buys and sells shows both prices with what they are paid in, such as `B $2 S $1`, or `B2 S1 Diamond` when it is paid in an item. An admin shop shows Admin Shop as its owner. Prices of 1,000 and up are shortened on the sign, such as `$100k`, `$10m` or `$1.5q`, while chat messages show the full price.

The mode line of a Buy shop also shows how many are left, such as **Selling: 1 - 58**, shortened from 1,000 up, such as **Selling: 1 - 1.2k**. Buy & Sell shops and admin shops leave the count out. A [disabled](edit-player-shop.md#enabled) shop shows \[Disabled] on the mode line. When a shop that sells to players no longer holds enough for one trade, the mode line turns into a bold \[Out of Stock] and the owner's name turns red until it is restocked. A shop that buys from players shows \[Chest Full] the same way when its container has no room for one more trade. The price hologram shows the same two states. The sign is checked after every trade, when the shop's container is closed, a second after a hopper or hopper minecart moves items in or out, and when its chunk loads.

A sign line holds 15 characters, so a longer line is cut short and the owner is told which one. The text comes from the player-shops.sign section of the translations file.

## Navigation

| Features | Description |
| --- | --- |
| [Item](edit-player-shop.md#item) | The item the sign trades. |
| [Amount](edit-player-shop.md#amount) | How many change hands in one click. |
| [Mode](edit-player-shop.md#mode) | Whether players buy, sell or both. |
| [Enabled](edit-player-shop.md#enabled) | Stop every trade without removing the shop. |
| [Buy Price](edit-player-shop.md#buy-price) | What a player pays the owner. |
| [Sell Price](edit-player-shop.md#sell-price) | What the owner pays a player. |
| [Currency](edit-player-shop.md#currency) | What an admin shop is priced in. |
| [Remove](edit-player-shop.md#remove) | Break the sign to take it down. |
| [Trading](trading.md) | Buying and selling on a sign. |
| [Protection](trading.md#protection) | Who can break or open the shop. |
| [Owner Notices](trading.md#owner-notices) | The messages an owner gets about their trades. |
| [Shop List](#shop-list) | Every player shop in one menu. |
| [Find a Shop](#find-a-shop) | The nearest shops that sell or buy an item. |
| [Market](#market) | Every traded item with its cheapest seller and best buyer. |
| [Discount](edit-player-shop.md#discount) | A timed price cut on a shop. |
| [Edit By Command](#edit-by-command) | Change the shop you look at without the editor. |
| [Map Markers](settings.md#map-markers) | Player shops on BlueMap, dynmap and squaremap. |
| [Transfer](#transfer) | Hand a shop to another player. |
| [Inactive Owners](#inactive-owners) | Remove the shops of players who stopped playing. |
| [Bulk Removal](#bulk-removal) | Remove empty shops, or every shop of a player or a world. |
| [Settings](settings.md) | Turn player shops on or off, the creation cost and the limit. |

## Shop List

The player shop commands are under `/chestshop`, or `/cs`, which can be renamed or turned off with [Chest Shop Command](settings.md#chest-shop-command).

`/chestshop list` lists every player shop with an item, with its [name](edit-player-shop.md#name), owner, amount and prices. Where a shop is stays hidden from players; admins see it in the [Player Shops Editor](#player-shops-editor). `/chestshop list <search>` keeps only the shops whose item, owner or name contains the search. It needs `phoenixshop.sign.list`, which everyone has by default.

Each entry also shows the item's own enchantments and lore.

Left-click a shop to teleport in front of its sign. That needs [Teleport](settings.md#teleport) on and `phoenixshop.sign.teleport`, given to everyone by default, and the shop's [Allow Teleport](edit-player-shop.md#allow-teleport) on. A shop with it off does not offer the click and says so instead, unless you own it or hold `phoenixshop.sign.admin`. Right-click it to trade with it from where you stand, which needs [Remote Trading](settings.md#remote-trading) on and `phoenixshop.sign.remote`, given to everyone by default.

The **Filter** button at the bottom shows all shops, only the ones selling, or only the ones buying. The **Order** button sorts them by their price for one item, lowest or highest first; on All, a shop that sells is sorted by its buy price and one that only buys by its sell price. **Show Only My Own** next to it lists only your own shops.

## Find a Shop

`/chestshop find <search>` opens a menu of the shops that sell the item and the shops that buy it, the ones in your world first and closest first, with the owner, amount, price and location. Add `selling` or `buying` at the end to open it with the Filter already set to that side. It needs `phoenixshop.sign.find`, which everyone has by default.

The search matches every word you type against the item's name, its material and its custom item id, so `/chestshop find vote key` finds a PhoenixCrates vote key (`phoenixcrates:key:vote`), and `/chestshop find adamantium` or `/chestshop find nexo:adamantium_ingot` finds a Nexo item. Shops whose item matches through its plugin id are listed before shops that only match by name, so the real item comes first. Without a search it looks for what you hold in your main hand. Tab completion offers the names of the items that are in shops, and the id of a custom item you hold.

Each shop also shows how many items it has in stock, or how much room is left in a shop that buys. Shops in a loaded area show the live count, and the others the count from their last trade or restock. Its clicks and its Filter and Order buttons work like the [Shop List](#shop-list). A Buy & Sell shop is listed under Selling only while it has stock, and under Buying only while its container has room.

A shop that sells is listed only while it holds enough for one trade, and a shop that buys only while its container has room. Admin shops always pass this check, and [disabled](edit-player-shop.md#enabled) shops are left out. A shop whose chunk is not loaded is listed without the check, since its container cannot be read.

The **Price Overview** at the top sums up the item for one piece: how many shops sell it and the lowest and average price, how many buy it and the best and average offer, and the average price it actually traded at over the last 30 days. Only shops priced in the currency most of them use count, and shops paid in items are left out. Trades made before this overview existed carry no price and are not counted.

## Market ⭐

`/chestshop market` lists every item that is in a chest shop once, with the cheapest shop selling it and the shop paying the most for it, both for one piece, and how many shops sell and buy it. Left-click an item to open [Find a Shop](#find-a-shop) for it. The **Order** button sorts by the number of shops, by name, or cheapest first. The same item priced in two currencies shows as two entries, and shops paid in items, disabled shops and shops without a price are left out. It needs `phoenixshop.sign.find`, and the menu can be changed in menus/chest-shops/market.yml.

## Edit By Command

Look at a chest shop's sign or container and change it without opening the editor:

| Command | Changes |
| --- | --- |
| `/chestshop price <buy\|sell> <price>` | The [Buy Price](edit-player-shop.md#buy-price) or [Sell Price](edit-player-shop.md#sell-price). |
| `/chestshop amount <amount>` | The [Amount](edit-player-shop.md#amount). |
| `/chestshop mode <buy\|sell\|both>` | The [Mode](edit-player-shop.md#mode). |
| `/chestshop name <name>` | The [Name](edit-player-shop.md#name), `-` clears it. |
| `/chestshop discount <percent> <length>` | Starts a [Discount](edit-player-shop.md#discount), such as `20 2h`; `off` ends it. |

Only the owner, or a player with `phoenixshop.sign.admin`, can use them, and they need `phoenixshop.sign.create`. When an admin changes another player's shop this way, the owner is told who changed what if they are online; add `-s` at the end, such as `/chestshop discount 20 2h -s`, to change it without telling them. The same checks as the editor apply, so a price outside the [Price Limits](settings.md#price-limits) is refused with the reason.

## Player Shops Editor

**Chest Shops** on the main editor menu first asks for **Player Shops**, **Admin Shops** or the server-wide [Settings](settings.md). The first two list every shop of that type on the server, including imported shops still waiting for their chunk to load. Its Status toggle turns player shops on or off. Filter the list by mode, or by text in the item, owner or shop name. From there an admin can open any shop's editor, teleport to it, take a copy of its item, or remove it, with the usual refund rules. The shop editor opened from here leaves out the Admin Shop toggle.

<figure><img src="../../.gitbook/assets/chest-shops/player-shops-editor.png" alt="" width="563"><figcaption><p>Player Shops (Iron Ingot)</p></figcaption></figure>

Each entry also shows whether a custom item from Nexo, ItemsAdder, MMOItems or another supported item plugin still matches that plugin's current version of it. **Outdated** means the plugin changed the item after the shop was made. Trades still work, since custom items match by id, but the shop's sign, display and menus keep showing the old copy. **Item or plugin missing** means the plugin no longer has that item, or the item carries the tags of a plugin that is not installed. Not every item plugin leaves such tags, so an item from an uninstalled plugin can still show as up to date. An item payment is checked the same way. When the shop's chunk is loaded, the entry also counts the old copies sitting in its container; an ender chest shop is only counted while its owner is online. The Item Status filter narrows the list to outdated or missing shops.

Press the drop key (Q) on an outdated entry to replace the shop's item, and its payment item if that is outdated too, with the current version. The trade amount stays the same. Items already in the container are not touched.

## Transfer

An owner hands a shop to another player by looking at its sign or container and running `/chestshop transfer <player>`. It needs `phoenixshop.sign.transfer`, which everyone has by default. The new owner has to be online or have played on the server before, and the shop has to fit within their [limit](settings.md#max-per-player). For an offline player the Max Per Player setting counts, since their permissions cannot be read.

The shop keeps its item, prices, contents, name and history, and the sign shows the new owner. The new owner is taken off its staff, and sale notices still waiting for the old owner are dropped. A later [refund](settings.md#refund-on-remove) goes to the new owner. Both players are told if they are online.

With `phoenixshop.sign.admin`, an admin can transfer any shop they look at, whatever the new owner's limit, and `/chestshop transferall <from> <to>` moves every shop of one player to another. Admin shops cannot be transferred.

## Inactive Owners

With [Purge Inactive Days](settings.md#purge-inactive-days) above 0, the shops of owners who have not played for that many days are removed shortly after the server starts and once a day after that. Admin shops are never removed, and neither are the shops of online owners or of owners the server has no last-played time for. The sign is removed like any other removal, the container keeps everything inside it, and nothing is refunded. The console logs how many shops were removed.

`/chestshop purge [days]` shows how many shops would go, using the setting when no days are given. `/chestshop purge <days> confirm` removes them. It needs `phoenixshop.sign.admin`.

## Bulk Removal

Each of these commands first shows how many shops would go, and removes them when run again with `confirm`. They need `phoenixshop.sign.admin`.

| Command | Removes |
| --- | --- |
| `/chestshop clean [confirm]` | The shops in loaded chunks that sell to players and hold less than one trade. Admin shops and ender chest shops are skipped. |
| `/chestshop removeall <player> [confirm]` | Every shop that player owns. Admin shops are kept. |
| `/chestshop removeworld <world> [confirm]` | Every chest shop in that world, admin shops included. |

The sign is removed, the container keeps everything inside it, and nothing is refunded.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/player-shops

---

# ✏️ Edit Player Shop

> **Info:**
The owner opens this menu by right-clicking their own sign, and it opens by itself when a shop is made. Every change is saved and written onto the sign straight away.

## Item

The item the sign trades. Drop an item from your inventory onto the slot. The item is copied exactly, name, lore and enchantments included, and only an identical item can be sold into the shop. An item from ItemsAdder, Nexo, ExecutableItems, PhoenixCrates and the other supported plugins is matched by its id instead, so the shop keeps trading it after that plugin changes the item's look or lore. The stack size you drop also becomes the [Amount](#amount).

<figure><img src="../../.gitbook/assets/edit-player-shop/item.png" alt="" width="563"><figcaption><p>Your Shop (Item)</p></figcaption></figure>

A sign with no item yet refuses every trade. Items on the server's [Blocked Items](settings.md#blocked-items) list cannot be dropped here.

## Amount

How many of the item change hands in one click. It can go above one stack, up to [Max Amount](settings.md#max-amount), and the prices are for that whole amount.

<figure><img src="../../.gitbook/assets/edit-player-shop/amount.png" alt="" width="563"><figcaption><p>Your Shop (Amount)</p></figcaption></figure>

## Mode

Click to choose what customers can do on the sign.

<figure><img src="../../.gitbook/assets/edit-player-shop/mode.png" alt="" width="563"><figcaption><p>Your Shop (Mode)</p></figcaption></figure>

| Mode | Customers |
| --- | --- |
| Buy | Buy out of the container. |
| Sell | Sell into the container, and the owner pays them. |
| Buy & Sell | Buy with a right-click, sell with a left-click. |

## Allow Teleport

Whether other players can teleport to this shop from the [shop list](README.md#shop-list) and the [find menu](README.md#find-a-shop). With it off they are told teleporting is disabled, the owner included; only players with `phoenixshop.sign.admin` still can.

<figure><img src="../../.gitbook/assets/edit-player-shop/allow-teleport.png" alt="" width="563"><figcaption><p>Your Shop (Allow Teleport)</p></figcaption></figure>

## Enabled

Turn it off to stop every trade on the shop without removing it. While it is off, the sign's mode line shows \[Disabled], the owner's name turns red, the [Price Hologram](#price-hologram) says the shop is disabled, and the shop is left out of the find menu.

<figure><img src="../../.gitbook/assets/edit-player-shop/enabled.png" alt="" width="563"><figcaption><p>Your Shop (Enabled)</p></figcaption></figure>

## Buy Price

What a customer pays the owner for one click's worth of the item. Click and type the amount, in a dialog where the server supports one, otherwise in chat. Shorthands from `k` up to `q`, such as `1.5k`, `2m` or `10q`, are accepted. A price has to be at least 0.01 and have at most 2 decimals; a side with no price set does not trade. A price outside the server's [Price Limits](settings.md#price-limits) is refused, and on a Both shop the sell price cannot be higher than the buy price unless [Allow Sell Above Buy](settings.md#allow-sell-above-buy) is on.

<figure><img src="../../.gitbook/assets/edit-player-shop/buy-price.png" alt="" width="563"><figcaption><p>Your Shop (Buy Price)</p></figcaption></figure>

## Sell Price

What the owner pays a customer for one click's worth of the item. It is typed the same way, shorthands included. The money comes out of the owner's own balance, so a sale is refused when the owner cannot afford it.

<figure><img src="../../.gitbook/assets/edit-player-shop/sell-price.png" alt="" width="563"><figcaption><p>Your Shop (Sell Price)</p></figcaption></figure>

## Currency ⭐

What the sign is priced in. On an [admin shop](README.md#admin-shops), left-click swaps between the currency types the server has installed, and right-click picks the currency within the type. The Item currency is not offered there, and the Placeholder currency needs Premium.

<figure><img src="../../.gitbook/assets/edit-player-shop/currency.png" alt="" width="563"><figcaption><p>Your Shop (Currency)</p></figcaption></figure>

On a player's own shop the option only shows when the server allows more than one currency in [Currencies](settings.md#currencies), and offers only those. Otherwise the shop is priced in the default currency. Its signs, hologram, shop list, find results and messages all show prices in the chosen currency, and the owner is paid in it. With a currency that only reaches online players, such as experience, see [Buying and Selling](trading.md#buying-and-selling) for what happens while the owner is offline.

<figure><img src="../../.gitbook/assets/edit-player-shop/player-currency.png" alt="" width="563"><figcaption><p>Your Shop (Currency, player shop)</p></figcaption></figure>

> **Warning:**
A sign priced in a currency whose plugin is not installed refuses every trade until it is. The editor warns about it on this option.

## Pay With Item ⭐

Drop an item here to price the shop in that item instead of money, such as diamonds or a custom coin. The buy and sell prices then become how many of it change hands, so they have to be whole numbers. A buyer's payment goes into the container, and the shop pays sellers out of it, so the owner has to keep it stocked. Left-click the slot with an empty hand to take the item off and go back to money. This is also how a shop barters one item for another.

<figure><img src="../../.gitbook/assets/edit-player-shop/pay-with-item.png" alt="" width="563"><figcaption><p>Your Shop (Pay With Item)</p></figcaption></figure>

## Name

A name for the shop of up to 32 characters. It shows in the shop's information panel, the [Shop List](README.md#shop-list) and the Player Shops editor, and searches in both lists match it. Colour codes are removed, and the name is not written on the sign. Type `-` to clear it.

<figure><img src="../../.gitbook/assets/edit-player-shop/name.png" alt="" width="563"><figcaption><p>Your Shop (Shop Name)</p></figcaption></figure>

## Display

How the traded item is shown on the container. It is only offered while [Display Items](settings.md#display-items) is on.

<figure><img src="../../.gitbook/assets/edit-player-shop/display.png" alt="" width="563"><figcaption><p>Your Shop (Display)</p></figcaption></figure>

| Style | Shows |
| --- | --- |
| None | Nothing. |
| Floating | The item above the container, bobbing up and down and spinning. |
| Large | The same, at a bigger size. |
| Glass Case | The item turning slowly inside a small glass block on top. |
| Flat | The item lying still on top, facing the sign. When the sign stands on the container, the item sits on the side the sign faces instead. |
| Orbit | Smaller copies of the item circling slowly above the container. One copy per 16 items in the [Amount](#amount), between 2 and 6. |

## Price Hologram

Shows the shop's prices above the displayed item, along with how many items are left, or an out-of-stock line once there are fewer than one click's worth. It updates after every trade, whenever the container is closed, and a second after a hopper or hopper minecart moves items in or out. The stock line is left out on admin shops, on Sell shops, and on ender chest shops while the owner is offline. Needs a [Display](#display) style other than None.

<figure><img src="../../.gitbook/assets/edit-player-shop/price-hologram.png" alt="" width="563"><figcaption><p>Your Shop (Price Hologram)</p></figcaption></figure>

## Mode Glow

Gives the displayed item a coloured outline matching the [Mode](#mode): red for Buy, green for Sell and gold for Both. Needs a [Display](#display) style other than None.

<figure><img src="../../.gitbook/assets/edit-player-shop/mode-glow.png" alt="" width="563"><figcaption><p>Your Shop (Mode Glow)</p></figcaption></figure>

## Player Limits ⭐

Caps how many items one player can buy and how many they can sell on this shop within a time window, such as 64 a day. Each side has its own limit, and 0 leaves that side open. A player's window starts with their first limited trade and resets once it has run out, so the count is not shared by everyone on a fixed clock.

<figure><img src="../../.gitbook/assets/edit-player-shop/player-limits.png" alt="" width="563"><figcaption><p>Your Shop (Player Limits)</p></figcaption></figure>

A customer over the limit is told how many they have left and when it resets, and the info panel shows the same. With [Partial Trades](trading.md#partial-trades) on, a trade larger than what is left goes through for the rest of the allowance.

## Discount ⭐

Lowers the [Buy Price](#buy-price) by a percentage, from 1 to 90, for a set length such as `2h` or `1d`. Set the percentage and length, then turn the discount on. While it runs, the sign, the [Price Hologram](#price-hologram), the shop list, find and the market all use the lowered price, the hologram adds a "% off" line, and the info panel shows the old price and the time left. It ends by itself and the owner is told. Only the buy side is discounted, so a Sell shop cannot run one, and neither can a shop [paid with an item](#pay-with-item). `/chestshop discount` does the same from the [command line](README.md#edit-by-command).

## Staff ⭐

Players who can open the container to restock it or take the takings out. They cannot change the shop, break it or remove it. A player has to be online to be added, and a vanished player counts as offline, so adding one gives nothing away. A shop takes up to 7, and removing one asks for confirmation first.

<figure><img src="../../.gitbook/assets/edit-player-shop/staff.png" alt="" width="563"><figcaption><p>Your Shop (Staff)</p></figcaption></figure>

## History

The latest 20 trades on the shop, newest first, with the customer, the amount, what was paid and when.

<figure><img src="../../.gitbook/assets/edit-player-shop/history.png" alt="" width="563"><figcaption><p>Your Shop (History)</p></figcaption></figure>

## Logs

Opened from the [Staff](#staff) menu. What the shop's staff put into the container or took out of it, newest first, with who, which item, how many and when. Each time a staff member closes the container, every item they changed becomes one entry. The owner's own restocking is not logged, and a shop keeps its latest 50 entries.

<figure><img src="../../.gitbook/assets/edit-player-shop/logs.png" alt="" width="563"><figcaption><p>Your Shop (Logs)</p></figcaption></figure>

## Admin Shop

Shown only to a player with `phoenixshop.sign.admin`. Turns the shop into an [admin shop](README.md#admin-shops) and back. An admin shop gets its own [Currency](#currency); turning it back into a player shop resets the currency to the default one unless players are allowed to use it. The creation cost already paid stays with the shop, so a later refund still goes to the owner.

## Remove

Break the sign or the container to take the shop down. The sign is removed without dropping, since the plugin placed it. The container becomes a normal container again, with everything still inside it. With [Refund On Remove](settings.md#refund-on-remove) on, the creation cost paid for the shop comes back to the owner.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/player-shops/edit-player-shop

---

# ⚙️ Settings

> **Info:**
These options are in chest-shops.yml, except Chest Shop Command, which is in the commands section of config.yml. Servers that had them in the player-shops section of config.yml get them moved there on the first start. All of them except Price Limits and Chest Shop Command can also be changed in **Editor > Chest Shops > Settings**, grouped into Creating Shops, Trading, Items & Prices, Displays and Teleport & Remote, where they apply at once.

chest-shops.yml:

```yaml
enabled: false
creation-cost: 0
max-per-player: 0
refund-on-remove: true
max-amount: 3456
blocked-items: []
blocked-worlds: []
sign-material: OAK_SIGN
protected-names: []
short-prices: true
click-confirm:
  enabled: true
  minutes: 5
display-items: true
glow-distance: 6
hologram-distance: 6
tax-percent: 0
allow-sell-above-buy: false
price-limits: {}
partial-trades: true
purge:
  inactive-days: 0
claims:
  require-claim: false
map-markers:
  enabled: true
trade-click: INSTANT
teleport: true
teleport-countdown: 3
remote-trading: false
currencies:
  - money
```

config.yml:

```yaml
commands:
  chest-shop:
    enabled: true
    alternative: chestshop
    aliases:
      - cs
```

## Enabled

Turns player shops on or off for the whole server. They are off until you turn them on. While off, nobody can trade on a player shop, the owner included, and left-clicking a container makes no new one. Existing shops stay where they are and work again once it is back on. On Lite, [admin shops](README.md#admin-shops) ignore it: they keep trading and can still be made while it is off.

<figure><img src="../../.gitbook/assets/chest-shop-settings/enabled.png" alt="" width="563"><figcaption><p>Settings (Chest Shops)</p></figcaption></figure>

It is also the Status toggle in **Editor > Sign Shops > Settings** and in the **Player Shops** editor.

## Click Creation

How hitting a container with an item makes a shop. Shift + Left-Click is the default, so a normal Left-Click always breaks the container. Left-Click twice asks for a second click on the same container with the same item within 3 seconds.

## Creation Cost

What a player pays once, when the shop is made. It is charged in the Vault currency, and a player who cannot afford it gets no shop. Set it to 0 to make shops free.

<figure><img src="../../.gitbook/assets/chest-shop-settings/creation-cost.png" alt="" width="563"><figcaption><p>Creating Shops (Creation Cost)</p></figcaption></figure>

> **Warning:**
With a cost above 0 and no Vault economy installed, nobody can create a player shop.

## Max Per Player

How many shops one player can own at a time. Removing a shop frees a place. Set it to 0 for no limit. On Lite the limit is never higher than 25, or 30 on a [linked server](../../plugin-information/licensing.md#linking-a-lite-server), and 0 means that cap.

<figure><img src="../../.gitbook/assets/chest-shop-settings/max-per-player.png" alt="" width="563"><figcaption><p>Creating Shops (Max Per Player)</p></figcaption></figure>

A permission overrides it per player. `phoenixshop.sign.limit.<number>` sets that player's limit, and the highest one they hold counts. `phoenixshop.sign.limit.unlimited` removes the limit. On Lite neither the setting nor a permission can go above that cap.

## Refund On Remove

Gives the owner back what they paid for the sign when the shop is removed, whether they take it down from its menu or break the sign or container. The refund is what was paid at the time, even when the Creation Cost has changed since.

<figure><img src="../../.gitbook/assets/chest-shop-settings/refund-on-remove.png" alt="" width="563"><figcaption><p>Creating Shops (Refund On Remove)</p></figcaption></figure>

## Max Amount

The highest [Amount](edit-player-shop.md#amount) an owner can set on a shop, per click. It is also the most a customer can [choose to trade](trading.md#choosing-an-amount) at once.

<figure><img src="../../.gitbook/assets/chest-shop-settings/max-amount.png" alt="" width="563"><figcaption><p>Trading (Max Amount)</p></figcaption></figure>

## Blocked Items

Materials that cannot be traded in player shops, such as `BEDROCK` or `SPAWNER`. An owner cannot put one on a shop, and a shop that already trades one refuses every trade.

<figure><img src="../../.gitbook/assets/chest-shop-settings/blocked-items.png" alt="" width="563"><figcaption><p>Items & Prices (Blocked Items)</p></figcaption></figure>

## Blocked Worlds

Worlds where no player shop can be created. A player with `phoenixshop.sign.bypass` can still put one up there. Shops that already exist in such a world keep working.

<figure><img src="../../.gitbook/assets/chest-shop-settings/blocked-worlds.png" alt="" width="563"><figcaption><p>Creating Shops (Blocked Worlds)</p></figcaption></figure>

## Sign Material

The sign placed on new shops. Any wooden sign works, given as its standing or wall name, such as `SPRUCE_SIGN` or `SPRUCE_WALL_SIGN`. Anything else falls back to oak. Hanging signs are not supported.

<figure><img src="../../.gitbook/assets/chest-shop-settings/sign-material.png" alt="" width="563"><figcaption><p>Creating Shops (Sign Material)</p></figcaption></figure>

## Short Prices

Shows prices of 1,000 and up shortened, such as `$250k` or `$1.5m`, in the chat messages, the amount prompt, the hologram and the shop menus. Smaller prices keep their cents. Turn it off to show the full amount there; signs always use the short form, since a sign line only fits 15 characters.

<figure><img src="../../.gitbook/assets/chest-shop-settings/short-prices.png" alt="" width="563"><figcaption><p>Items & Prices (Short Prices)</p></figcaption></figure>

## Click Confirm

Makes the first buy or sell click on a shop sign ask the player to click again, so nobody trades by accident. Once confirmed, clicks on that shop trade straight away until `minutes` pass without trading there, 5 by default. Set `enabled` to `false` to trade on every click.

<figure><img src="../../.gitbook/assets/chest-shop-settings/click-confirm.png" alt="" width="563"><figcaption><p>Trading (Click Confirm)</p></figcaption></figure>

## Protected Names

Names that only real plugin items may carry, on top of the ones the plugin [finds by itself](README.md#fake-items). A renamed item with one of these names is refused. Write the name as it reads in game; `*` matches anything, so `*key*` covers every renamed item with key in its name.

<figure><img src="../../.gitbook/assets/chest-shop-settings/protected-names.png" alt="" width="563"><figcaption><p>Items & Prices (Protected Names)</p></figcaption></figure>

## Display Items

Lets owners show their item on the container, see [Display](edit-player-shop.md#display). Turning it off removes every shown item at once.

<figure><img src="../../.gitbook/assets/chest-shop-settings/display-items.png" alt="" width="563"><figcaption><p>Displays (Display Items)</p></figcaption></figure>

## Glow Distance

How many blocks away a player still sees a shop's [Mode Glow](edit-player-shop.md#mode-glow). A glow outline shows through walls, so a short distance keeps players from tracking shops through the ground. Past it, the item shows without the outline. The distance grows or shrinks with each player's Entity Distance video setting.

<figure><img src="../../.gitbook/assets/chest-shop-settings/glow-distance.png" alt="" width="563"><figcaption><p>Displays (Glow Distance)</p></figcaption></figure>

## Hologram Distance

How many blocks away a player still sees a shop's [Price Hologram](edit-player-shop.md#price-hologram). It also follows each player's Entity Distance video setting.

<figure><img src="../../.gitbook/assets/chest-shop-settings/hologram-distance.png" alt="" width="563"><figcaption><p>Displays (Hologram Distance)</p></figcaption></figure>

## Tax Percent

The share of every money purchase that the owner does not receive. A buyer pays the full price, and the owner gets the price minus the tax, so 10 means owners keep 90%. Shops paid in items and admin shops are never taxed.

<figure><img src="../../.gitbook/assets/chest-shop-settings/tax-percent.png" alt="" width="563"><figcaption><p>Trading (Tax Percent)</p></figcaption></figure>

## Allow Sell Above Buy

While off, an owner cannot set a Both shop to pay sellers more than it charges buyers.

<figure><img src="../../.gitbook/assets/chest-shop-settings/allow-sell-above-buy.png" alt="" width="563"><figcaption><p>Trading (Allow Sell Above Buy)</p></figcaption></figure>

## Price Limits

The lowest and highest price per single item an owner can set, by material, with `default` covering every material not listed. A max of 0 means no upper limit. The limits are in the default currency, so shops paid in items or priced in another currency are not checked.

```yaml
price-limits:
  default:
    min: 0.1
    max: 0
  DIAMOND:
    min: 50
    max: 500
```

## Partial Trades

Lets a trade that cannot go through in full trade the part that can, at its share of the price, see [Partial Trades](trading.md#partial-trades). While off, such a trade is refused as a whole.

<figure><img src="../../.gitbook/assets/chest-shop-settings/partial-trades.png" alt="" width="563"><figcaption><p>Trading (Partial Trades)</p></figcaption></figure>

## Purge Inactive Days ⭐

Removes the shops of owners who have not played for this many days, checked shortly after startup and once a day. See [Inactive Owners](README.md#inactive-owners). Set it to 0 to keep every shop.

<figure><img src="../../.gitbook/assets/chest-shop-settings/purge-inactive-days.png" alt="" width="563"><figcaption><p>Creating Shops (Purge Inactive Days)</p></figcaption></figure>

## Require Claim

Lets a player make a shop only on a container inside a claim or region where they can build. WorldGuard, GriefPrevention, Lands and Towny are checked, whichever are installed. A spot that one of them protects against the player is refused even when another allows it. With none of them installed, nothing is checked. A player with `phoenixshop.sign.bypass` skips the check, and admin shops are never checked. Existing shops stay when a claim is removed.

<figure><img src="../../.gitbook/assets/chest-shop-settings/require-claim.png" alt="" width="563"><figcaption><p>Creating Shops (Require Claim)</p></figcaption></figure>

## Map Markers ⭐

Shows every player shop with an item as a marker on BlueMap, dynmap and squaremap, whichever are installed, in a layer called Player Shops. A marker shows the shop's name if it has one, the item, the amount, the owner and the prices, and follows the shop as it is created, edited or removed. Nothing is shown while player shops are turned off. The marker text comes from the player-shops.map section of the translations file.

<figure><img src="../../.gitbook/assets/chest-shop-settings/map-markers.png" alt="" width="563"><figcaption><p>Displays (Map Markers)</p></figcaption></figure>

## Trade Click

What a customer's click on a shop sign does. `INSTANT`, the default, trades the shop's fixed amount on every click: right-click buys, left-click sells. `PROMPT` asks how many to buy or sell instead. Sneaking and right-clicking asks for an amount either way. See [Buying and Selling](trading.md#buying-and-selling).

<figure><img src="../../.gitbook/assets/chest-shop-settings/trade-click.png" alt="" width="563"><figcaption><p>Trading (Trade Click)</p></figcaption></figure>

## Teleport

Lets [/chestshop list](README.md#shop-list) and [/chestshop find](README.md#find-a-shop) teleport a player to a shop. It also needs `phoenixshop.sign.teleport`, which everyone has by default, and each shop decides with its own [Allow Teleport](edit-player-shop.md#allow-teleport).

<figure><img src="../../.gitbook/assets/chest-shop-settings/teleport.png" alt="" width="563"><figcaption><p>Teleport & Remote (Teleport)</p></figcaption></figure>

## Teleport Countdown

How many seconds a player waits before a teleport to a shop happens. Moving in that time cancels it. Set it to 0 to teleport straight away.

<figure><img src="../../.gitbook/assets/chest-shop-settings/teleport-countdown.png" alt="" width="563"><figcaption><p>Teleport & Remote (Teleport Countdown)</p></figcaption></figure>

## Remote Trading ⭐

Lets players buy from or sell to a shop without walking to it: right-click an entry in [/chestshop list](README.md#shop-list), or click **\[Trade]** on a [/chestshop find](README.md#find-a-shop) result. It opens the buy or sell menu with the item preview. It also needs `phoenixshop.sign.remote`, which everyone has by default. A player cannot trade remotely with their own shop or with a [disabled](edit-player-shop.md#enabled) one.

<figure><img src="../../.gitbook/assets/chest-shop-settings/remote-trading.png" alt="" width="563"><figcaption><p>Teleport & Remote (Remote Trading)</p></figcaption></figure>

On Folia, a shop can only be traded with remotely while it is in the same region as the player, which in practice means nearby. A shop further away is refused with a message asking the player to get closer.

## Currencies ⭐

The currencies players can price their own shops in, by currency id. With two or more listed and installed, the shop editor gets a [Currency](edit-player-shop.md#currency) choice; with one, every player shop uses the default currency as before. A currency whose plugin is missing is left out of the choice. Taking a currency off the list, or moving to Lite, keeps the shops already priced in it trading in it. On Lite the choice is not offered.

<figure><img src="../../.gitbook/assets/chest-shop-settings/currencies.png" alt="" width="563"><figcaption><p>Items & Prices (Currencies)</p></figcaption></figure>

```yaml
currencies:
  - money
  - points
```

## Chest Shop Command

The name and aliases of the player shop command, `/chestshop` and `/cs` by default. On Lite it only holds `notifications`. Changes apply with `/pshop reload`, without a restart, and turning it off removes the command. If another plugin already owns one of these names, PhoenixShop takes it over, and that plugin's command stays reachable with its prefix, such as `/worldedit:cs`.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/player-shops/settings

---

# 🤝 Trading

## Buying and Selling

Customers click the sign. On a Buy sign a right-click buys, on a Sell sign a right-click sells, and on a Both sign a right-click buys while a left-click sells. What the click does depends on [Trade Click](settings.md#trade-click):

| Trade Click | A click on the sign |
| --- | --- |
| Instant (default) | Trades the [Amount](edit-player-shop.md#amount) set on the shop straight away. Always used on Lite. |
| Prompt | Asks how many to buy or sell, see [Choosing an Amount](#choosing-an-amount). |

With [Click Confirm](settings.md#click-confirm) on, the first buy or sell click on a shop only says **Click again to buy** (or sell), with the amount and price; a second click within 10 seconds trades. After that the clicks on that shop trade straight away until 5 minutes pass without trading there. A click that would be refused anyway, such as no price set, nothing in stock or not enough money, is refused straight away without asking.

The info panel lists the shop's owner, item, stock, room left and prices. Hovering its **\[Item Preview]** tag shows the item's name, enchantments and lore, and clicking it opens the item in a menu with its full tooltip. On a shop [paid in an item](edit-player-shop.md#pay-with-item), the buy and sell lines get their own **\[Item Preview]** for the payment item. The click confirmation and the bought and sold messages show the item in brackets the same way, and the price too on a shop paid in an item: hovering it shows the item, and clicking it opens the preview. Sneaking and left-clicking the sign shows the panel, and sneaking and right-clicking [trades a chosen amount](#choosing-an-amount).

Bedrock players, detected through Floodgate or Geyser, cannot click chat, so they get the item name as plain text instead of the bracketed link. Their info panel opens as a form with the same lines and a **View** button for the item, and one for the payment item on a shop paid in an item, which opens the same preview menu. They type the amount for a chosen-amount trade in a form as well.

No permission is needed to trade on a player shop. The owner right-clicking their own sign opens its editor instead of trading. An [admin shop](README.md#admin-shops) trades for everyone, the admin who made it included; open its editor with /pshop editshop while looking at it.

A trade is refused, with a message saying why, when:

| Buying | Selling |
| --- | --- |
| The container does not hold the full amount. | The customer does not carry the full amount. |
| The customer's inventory has no room for it. | The container has no room for it. |
| The customer cannot afford the price. | The owner cannot afford the price. |

Both directions are also refused while player shops are turned off, while the shop is [disabled](edit-player-shop.md#enabled), when the sign has no item, when the item is on the [Blocked Items](settings.md#blocked-items) list, when its currency is missing, and when the container behind it is gone. A shulker box shop never accepts shulker boxes. Experience, levels, item currencies, Placeholder currencies and ExcellentEconomy can only pay or charge a player who is online. On a shop priced in one of them, customers can still buy while the owner is offline: the owner's earnings wait and are paid the next time they join. Selling to that shop needs the owner online, since their balance cannot be checked or charged. An [ender chest shop](README.md#create-a-player-shop) only trades while its owner is online, whatever it is priced in.

## Choosing an Amount

Sneaking and right-clicking the sign asks how many items to trade instead of the shop's fixed Amount. On a Both sign a small menu first asks whether to buy or sell. It shows the shop's item in the middle with its full tooltip, with Buy and Sell on either side; a side the shop does not trade, or has no price for, is grayed out. The menu is [customizable](../../configurations/customize-menus.md#chest-shop-trade) and closes when the shop is removed. The amount is typed in a dialog where the server supports one, otherwise in chat, and the customer has to stay within 8 blocks of the sign unless they are [trading remotely](settings.md#remote-trading).

Typing `all` instead of a number buys as many as the customer can afford, carry and the shop has in stock, or sells every matching item they hold, up to [Max Amount](settings.md#max-amount). The word is set in the player-shops.amount-prompt section of the translations file.

The price is shared out per item: 10 items on a shop selling 64 for 640 cost 100. Money is rounded to the cent, and currencies that only use whole numbers, such as levels, to a whole number: what a buyer pays is rounded up and what a seller gets is rounded down. The prompt does not open while a shop is out of stock for buying, or its chest is full for selling. A shop [paid in items](edit-player-shop.md#pay-with-item) only accepts amounts that come to a whole number of its payment item, and the prompt names the multiple to use. One trade can move at most [Max Amount](settings.md#max-amount).

If the owner changes the shop's price, Amount, currency, item or payment item while the customer is still choosing, or removes the shop, the answer is refused and nothing is traded, so nobody pays a price they were not shown.

## Partial Trades

When a trade cannot go through in full, the part that can goes through and is charged for its share of the price. The customer is told they got fewer than they asked for.

| Buying | Selling |
| --- | --- |
| The container holds fewer than asked. | The container has room for fewer than offered. |
| | The owner can only afford part of it. |
| The customer's [Player Limits](edit-player-shop.md#player-limits) allow fewer. | The customer's Player Limits allow fewer. |

A shop paid in items only trades the largest part that still comes to whole payment items. Everything else in the refusal table above still refuses the whole trade. [Partial Trades](settings.md#partial-trades) turns this off.

## Protection

Only the owner can break the sign, break the container, or open the container. Everyone else is told whose shop it is. Both halves of a double chest are covered. Staff can open the container too, except on an ender chest shop.

Items cannot be pulled out of the container by a hopper or any other block, and nobody but the owner can place a hopper against it. Explosions, fire and pistons leave the sign and both halves of the container alone.

A player with `phoenixshop.sign.admin` gets the same access as the owner, so staff can open or remove any player shop.

> **Warning:**
Breaking the container the sign is on removes the shop and breaks its sign as well, since the sign has nothing left to trade out of. Breaking the half added later to make a double chest only turns the shop back into a single chest.

## Owner Notices

The owner is messaged after every trade on one of their signs, with the customer, the amount, the item and the price.

<figure><img src="../../.gitbook/assets/chest-shop-notifications/owner-notices.png" alt="" width="563"><figcaption><p>Notifications (Buy)</p></figcaption></figure>

When the owner is offline, the notices wait and are delivered the next time they join. Repeated trades by the same customer in the same direction are merged into one line with the totals added up, so twelve sales by one player read as a single notice. Each owner keeps at most 20 waiting notices across all of their signs, and the oldest are dropped first.

An online owner is also told when a trade leaves the shop without enough stock for another one, or the container without room for another sale, and when a customer finds it that way, at most once every 10 minutes per shop. That message ends with **\[Teleport]**, which takes the owner to the shop when its [Allow Teleport](edit-player-shop.md#allow-teleport) is on. A Bedrock owner, who cannot click it, gets a hint to run `/chestshop tp` instead, which with no shop named goes to the shop of their latest warning. An owner is also told when a player teleports to one of their shops.

An offline owner gets these stock warnings on their next join instead, as one **While you were away** summary with a line per shop and problem, however often it happened. Each line gets the same **\[Teleport]**. The summary shows at most 10 lines and counts the rest, and the same warning for that shop is held back for 10 minutes after it.

Earnings an offline owner could not be paid in the shop's currency are paid a second after they join, with one line per currency saying how much came in. They wait in the database, so a restart or reload loses nothing.

`/chestshop notifications` opens a menu where each player turns these on or off for their own shops: Buy, Sell, Teleport, Out of Stock and Chest Full. Trades made while Buy or Sell is off are not queued, and stock warnings are only queued and shown while Out of Stock or Chest Full is on. Payouts are always made. A player who had turned notices off with the old `/pshop notify` starts with all five off.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/player-shops/trading

---

# 🪙 Selling

> **Info:**
The server-wide sell settings are saved in config.yml and edited under **Editor > Settings > Sell Command**.

Players sell an item back to a shop for its sell price. An item with a sell price of 0 cannot be sold. Every sale, whichever way it is made, goes through the same checks as a sale in the shop menu, so requirements and the item's own sell commands still apply.

There are two ways to sell:

* **Inside a shop.** By default, right-clicking an item in a category opens a screen to pick how many to sell, and shift + right-click sells every one the player carries. [Bulk Selling](#bulk-selling) covers selling whole stacks at once.
* **With /sell.** Sells without opening a shop at all, from the hand, the whole inventory or a drop-in menu. See [The /sell Command](#the-sell-command).

`/sell` only sells into the shops on the [Whitelisted Shops](#whitelisted-shops) list.

## The /sell Command

`/sell` sells straight into your shops without opening one. It only sells into the [whitelisted shops](#whitelisted-shops) the player is allowed to open, and when there are none it tells the player there is no shop to sell to.

<figure><img src="../../.gitbook/assets/sell-command/sell-command.png" alt="" width="563"><figcaption><p>Settings (Sell Command)</p></figcaption></figure>

| Command | Permission | Description |
| --- | --- | --- |
| `/sell hand` | phoenixshop.sell.hand | Sells the stack in the main hand. |
| `/sell handall` | phoenixshop.sell.handall | Sells every stack identical to the one in the main hand. |
| `/sell inventory` | phoenixshop.sell.inventory | Sells everything in the inventory the shops buy. |
| `/sell menu` | phoenixshop.sell.menu | Opens the [sell menu](#sell-menu). |

All four permissions are given to operators only by default. Grant them to your player group to open `/sell` to everyone.

### /sell hand

Sells the stack the player is holding in the main hand. The off-hand is never touched. If none of the whitelisted shops buy it, nothing is sold and the player is told the shop does not buy that item.

### /sell handall

Sells the held stack and every other stack in the main inventory and hotbar that is identical to it, same material and same name, lore and data. Copies that differ in any way, such as a renamed one, are left alone.

### /sell inventory

Sells every item in the main inventory and hotbar that one of the whitelisted shops buys. Armor and the off-hand are left alone, and anything no shop buys stays where it is.

### Shulker Boxes

With **Sell Shulker Contents** on, `/sell inventory`, `/sell hand` and the [sell menu](#sell-menu) also sell what is inside shulker boxes. Whatever the shops do not buy stays in the box. It is on by default, and set under **Editor > Settings > Sell Command**.

<figure><img src="../../.gitbook/assets/sell-command/shulker-boxes.png" alt="" width="563"><figcaption><p>Sell Command (Sell Shulker Contents)</p></figcaption></figure>

* `/sell hand` on a box that holds items sells only its contents, never the box. An empty box is sold like any other item, if a shop buys it.
* `/sell inventory` empties the boxes first, then sells the loose items.
* The sell menu accepts a box when anything inside it can be sold, and its worth counts the contents.

AutoSell and sell chests never open shulker boxes.

### Minimum Sale

An item with a [minimum sale](../items/edit-item.md#minimum-sale) is skipped by `/sell` and AutoSell while the player carries fewer than that many.

### How Items Are Matched

Each shop is checked in whitelist order, and within a shop every enabled category and item in turn. The first item that matches a carried stack and has a sell price buys it, so a shop higher on the list always gets first pick.

An item sells in lots of its own amount. If a shop item is 16 cobblestone for a price, a player carrying 40 sells 32 and keeps the remaining 8.

Items whose currency is not available, or that the player does not meet the requirements for, are skipped.

### Earnings in Several Currencies

When the items sold are priced in different currencies, each currency is paid separately and the message lists every total, such as `$120, 4 Gems`.

## Sell Menu

> **Info:**
The menu's layout is menus/&lt;shop&gt;/sell-menu.yml, taken from the first whitelisted shop the player can open.

`/sell menu` opens a chest the player fills with the items they want to sell. Items the whitelisted shops do not buy are refused as they are put in, with the refused sound, so nothing the shops cannot pay for ever sits in the menu.

A shulker box is accepted when something inside it can be sold, while [Sell Shulker Contents](#shulker-boxes) is on.

Items go in by dragging, shift-clicking from the inventory, the hotbar number keys, or the swap-hands key for the off-hand item.

### Drop Slots

The slots items can be put in. By default these are the top five rows, with the bottom row kept for the border and the confirm button. Any slot that is not a drop slot is locked.

### Sell Items

The confirm button. Its lore shows what everything in the drop slots is worth, updated as items go in, and clicking it sells them and closes the menu.

Anything that could not be sold, such as a stack left over after selling in lots, goes back to the player's inventory, or is dropped at their feet if the inventory is full.

### Sell on Close

Whether closing the menu sells what is in it, the same as clicking Sell Items. On by default. When off, closing the menu without clicking Sell Items gives every item back.

This is only set in config.yml. While it is on, the Sell Items lore adds a line telling players that closing sells too.

> **Info:**
Bedrock players get a form instead of the chest while Bedrock sell forms are on. It lists every item in their inventory the shops buy, each with a toggle, and sells the ones left on.

## Whitelisted Shops

The list of shops `/sell` and the sell menu may sell into, in priority order. Only the shop called `shop` is on it by default, so a new shop is left out of `/sell` until you add it.

<figure><img src="../../.gitbook/assets/whitelisted-shops/whitelisted-shops.png" alt="" width="563"><figcaption><p>Sell Command (Whitelisted Shops)</p></figcaption></figure>

A player only sells into the shops on the list they are allowed to open, and a disabled shop is skipped. When none are left for a player, `/sell` tells them there is no shop to sell to.

### Priority

When more than one listed shop buys the same item, the one highest on the list gets it. Put a VIP shop with better prices above the regular one, and give it a permission: VIP players sell at the better price, and everyone else falls through to the regular shop.

<figure><img src="../../.gitbook/assets/whitelisted-shops/priority.png" alt="" width="563"><figcaption><p>Whitelisted Shops (Priority Reordering)</p></figcaption></figure>

**Add Shop** puts a shop at the bottom of the list, and left-clicking a listed shop removes it. To change the order, turn on **Priority Reordering** and click two shops to swap their places.

### Shop No Longer There

A shop that was deleted stays on the list, marked as missing, until you remove it. It is simply skipped when selling.

## Sell Feedback

> **Info:**
These settings are saved in config.yml. They apply to `/sell` and the sell menu, not to selling inside a shop, which uses the shop's own sounds.

### Refused Sound

The sound played when an item is refused by the sell menu, or when `/sell` finds nothing to sell. Written as `SOUND, volume, pitch`. Set it to `none` for silence.

<figure><img src="../../.gitbook/assets/sell-feedback/refused-sound.png" alt="" width="563"><figcaption><p>Sell Command (Refused Sound)</p></figcaption></figure>

### Sold Sound

The sound played after a sale. Written the same way, and `none` turns it off.

<figure><img src="../../.gitbook/assets/sell-feedback/sold-sound.png" alt="" width="563"><figcaption><p>Sell Command (Sold Sound)</p></figcaption></figure>

### Sold Title

Shows a title across the screen after a sale, with the money earned and how many items were sold. On by default.

<figure><img src="../../.gitbook/assets/sell-feedback/sold-title.png" alt="" width="563"><figcaption><p>Sell Command (Sold Title)</p></figcaption></figure>

### Title Time

How long the title stays on screen, in ticks. 20 ticks is 1 second, and the editor keeps it between 10 and 200. The fade-in and fade-out times are only set in the file.

<figure><img src="../../.gitbook/assets/sell-feedback/title-time.png" alt="" width="563"><figcaption><p>Sell Command (Title Time)</p></figcaption></figure>

### Sold Chat Message

Sends a chat message after a sale, with the money earned and how many items were sold. On by default. Turning both this and the title off leaves only the sound.

<figure><img src="../../.gitbook/assets/sell-feedback/sold-chat-message.png" alt="" width="563"><figcaption><p>Sell Command (Sold Chat Message)</p></figcaption></figure>

### Messages

The text of the title and the message lives in the translations file, under the sell section.

| Key | Default |
| --- | --- |
| sell.sold | You sold %items% %items\_word% for %money%. |
| sell.sold-title | +%money% |
| sell.sold-subtitle | You sold %amount% %items\_word% |
| sell.nothing-to-sell | You have nothing the shop will buy. |
| sell.nothing-sold | The shop doesn't buy any of those, so they were given back. |
| sell.returned | %amount% %items\_word% couldn't be sold and went back to your inventory. |
| sell.empty-hand | Hold the item you want to sell. |
| sell.cannot-sell-hand | The shop doesn't buy %item%. |
| sell.no-shops | There is no shop to sell to right now. |

| Placeholder | Description |
| --- | --- |
| %items% / %amount% | How many items were sold. In sell.returned, %amount% is how many were given back. |
| %items\_word% | "item" or "items", to match the count. |
| %money% | What the sale paid, one total per currency. |

## Off-Hand

Whether a player's off-hand item is sold depends on how they sell. There is no setting for this.

| Way of selling | Off-hand |
| --- | --- |
| Selling from a shop's item screen | Counted, together with the inventory. |
| Sell All and shift + right-click in a category | Counted, together with the inventory. |
| Bulk Sell | Counted, together with the inventory. |
| `/sell hand` | Never. Only the main hand is sold. |
| `/sell inventory` | Never. Only the main inventory and hotbar are sold. |
| Sell menu | Only when the player puts it in, with the swap-hands key over a drop slot. |

When a sale counts the off-hand and it holds a matching item, the inventory is used first and the off-hand makes up the rest. Buying from a shop works the same way: what does not fit in the inventory goes into the off-hand, if it is empty or holds the same item.

Armor slots are never sold from.

## Bulk Selling

Inside a shop, players have three ways to sell more than one lot at a time. All of them count the [off-hand](#off-hand) along with the inventory.

### Sell All Click

By default, shift + right-clicking an item in a category sells every one of it the player carries, without opening any screen. This needs the `phoenixshop.sell.all` permission, which only operators have unless you grant it.

The click is set by the click mappings in config.yml, where `SELL_ALL` can be moved to another click or removed.

### Sell All Button

The item's sell screen has a **Sell All** button that sets the amount to everything the player carries, showing what it would pay before they confirm. It needs the same `phoenixshop.sell.all` permission, and shows a barrier to players without it.

### Bulk Sell

The **Bulk Sell** button on the item's sell screen opens a menu with one option per number of stacks, from 1 up to 9, each showing the amount and what it pays. Clicking one sells that many at once, and the menu stays open for another sale. No extra permission is needed.

A stack here is a full stack of the item, 64 for most items and 16 or 1 for items that stack lower.

> **Info:**
The Bulk Sell menu's layout is menus/&lt;shop&gt;/bulk-sell.yml, one per shop.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/selling

---

# 📦 Bulk Selling

## Bulk Selling

Inside a shop, players have three ways to sell more than one lot at a time. All of them count the [off-hand](offhand.md) along with the inventory.

## Sell All Click

By default, shift + right-clicking an item in a category sells every one of it the player carries, without opening any screen. This needs the `phoenixshop.sell.all` permission, which only operators have unless you grant it.

The click is set by the click mappings in config.yml, where `SELL_ALL` can be moved to another click or removed.

## Sell All Button

The item's sell screen has a **Sell All** button that sets the amount to everything the player carries, showing what it would pay before they confirm. It needs the same `phoenixshop.sell.all` permission, and shows a barrier to players without it.

## Bulk Sell

The **Bulk Sell** button on the item's sell screen opens a menu with one option per number of stacks, from 1 up to 9, each showing the amount and what it pays. Clicking one sells that many at once, and the menu stays open for another sale. No extra permission is needed.

A stack here is a full stack of the item, 64 for most items and 16 or 1 for items that stack lower.

> **Info:**
The Bulk Sell menu's layout is menus/&lt;shop&gt;/bulk-sell.yml, one per shop.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/selling/bulk-selling

---

# 🤚 Off-Hand

## Off-Hand

Whether a player's off-hand item is sold depends on how they sell. There is no setting for this.

| Way of selling | Off-hand |
| --- | --- |
| Selling from a shop's item screen | Counted, together with the inventory. |
| Sell All and shift + right-click in a category | Counted, together with the inventory. |
| Bulk Sell | Counted, together with the inventory. |
| `/sell hand` | Never. Only the main hand is sold. |
| `/sell inventory` | Never. Only the main inventory and hotbar are sold. |
| Sell menu | Only when the player puts it in, with the swap-hands key over a drop slot. |

When a sale counts the off-hand and it holds a matching item, the inventory is used first and the off-hand makes up the rest. Buying from a shop works the same way: what does not fit in the inventory goes into the off-hand, if it is empty or holds the same item.

Armor slots are never sold from.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/selling/offhand

---

# 🤑 The /sell Command

## The /sell Command

`/sell` sells straight into your shops without opening one. It only sells into the [whitelisted shops](whitelisted-shops.md) the player is allowed to open, and when there are none it tells the player there is no shop to sell to.

<figure><img src="../../.gitbook/assets/sell-command/sell-command.png" alt="" width="563"><figcaption><p>Settings (Sell Command)</p></figcaption></figure>

| Command | Permission | Description |
| --- | --- | --- |
| `/sell hand` | phoenixshop.sell.hand | Sells the stack in the main hand. |
| `/sell handall` | phoenixshop.sell.handall | Sells every stack identical to the one in the main hand. |
| `/sell inventory` | phoenixshop.sell.inventory | Sells everything in the inventory the shops buy. |
| `/sell menu` | phoenixshop.sell.menu | Opens the [sell menu](sell-menu.md). |

All four permissions are given to operators only by default. Grant them to your player group to open `/sell` to everyone.

## /sell hand

Sells the stack the player is holding in the main hand. The off-hand is never touched. If none of the whitelisted shops buy it, nothing is sold and the player is told the shop does not buy that item.

## /sell handall

Sells the held stack and every other stack in the main inventory and hotbar that is identical to it, same material and same name, lore and data. Copies that differ in any way, such as a renamed one, are left alone.

## /sell inventory

Sells every item in the main inventory and hotbar that one of the whitelisted shops buys. Armor and the off-hand are left alone, and anything no shop buys stays where it is.

## Shulker Boxes

With **Sell Shulker Contents** on, `/sell inventory`, `/sell hand` and the [sell menu](sell-menu.md) also sell what is inside shulker boxes. Whatever the shops do not buy stays in the box. It is on by default, and set under **Editor > Settings > Sell Command**.

<figure><img src="../../.gitbook/assets/sell-command/shulker-boxes.png" alt="" width="563"><figcaption><p>Sell Command (Sell Shulker Contents)</p></figcaption></figure>

* `/sell hand` on a box that holds items sells only its contents, never the box. An empty box is sold like any other item, if a shop buys it.
* `/sell inventory` empties the boxes first, then sells the loose items.
* The sell menu accepts a box when anything inside it can be sold, and its worth counts the contents.

AutoSell and sell chests never open shulker boxes.

## Minimum Sale

An item with a [minimum sale](../items/edit-item.md#minimum-sale) is skipped by `/sell` and AutoSell while the player carries fewer than that many.

## How Items Are Matched

Each shop is checked in whitelist order, and within a shop every enabled category and item in turn. The first item that matches a carried stack and has a sell price buys it, so a shop higher on the list always gets first pick.

An item sells in lots of its own amount. If a shop item is 16 cobblestone for a price, a player carrying 40 sells 32 and keeps the remaining 8.

Items whose currency is not available, or that the player does not meet the requirements for, are skipped.

## Earnings in Several Currencies

When the items sold are priced in different currencies, each currency is paid separately and the message lists every total, such as `$120, 4 Gems`.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/selling/sell-command

---

# 🔔 Sell Feedback

> **Info:**
These settings are saved in config.yml. They apply to `/sell` and the sell menu, not to selling inside a shop, which uses the shop's own sounds.

## Refused Sound

The sound played when an item is refused by the sell menu, or when `/sell` finds nothing to sell. Written as `SOUND, volume, pitch`. Set it to `none` for silence.

<figure><img src="../../.gitbook/assets/sell-feedback/refused-sound.png" alt="" width="563"><figcaption><p>Sell Command (Refused Sound)</p></figcaption></figure>

## Sold Sound

The sound played after a sale. Written the same way, and `none` turns it off.

<figure><img src="../../.gitbook/assets/sell-feedback/sold-sound.png" alt="" width="563"><figcaption><p>Sell Command (Sold Sound)</p></figcaption></figure>

## Sold Title

Shows a title across the screen after a sale, with the money earned and how many items were sold. On by default.

<figure><img src="../../.gitbook/assets/sell-feedback/sold-title.png" alt="" width="563"><figcaption><p>Sell Command (Sold Title)</p></figcaption></figure>

## Title Time

How long the title stays on screen, in ticks. 20 ticks is 1 second, and the editor keeps it between 10 and 200. The fade-in and fade-out times are only set in the file.

<figure><img src="../../.gitbook/assets/sell-feedback/title-time.png" alt="" width="563"><figcaption><p>Sell Command (Title Time)</p></figcaption></figure>

## Sold Chat Message

Sends a chat message after a sale, with the money earned and how many items were sold. On by default. Turning both this and the title off leaves only the sound.

<figure><img src="../../.gitbook/assets/sell-feedback/sold-chat-message.png" alt="" width="563"><figcaption><p>Sell Command (Sold Chat Message)</p></figcaption></figure>

## Messages

The text of the title and the message lives in the translations file, under the sell section.

| Key | Default |
| --- | --- |
| sell.sold | You sold %items% %items\_word% for %money%. |
| sell.sold-title | +%money% |
| sell.sold-subtitle | You sold %amount% %items\_word% |
| sell.nothing-to-sell | You have nothing the shop will buy. |
| sell.nothing-sold | The shop doesn't buy any of those, so they were given back. |
| sell.returned | %amount% %items\_word% couldn't be sold and went back to your inventory. |
| sell.empty-hand | Hold the item you want to sell. |
| sell.cannot-sell-hand | The shop doesn't buy %item%. |
| sell.no-shops | There is no shop to sell to right now. |

| Placeholder | Description |
| --- | --- |
| %items% / %amount% | How many items were sold. In sell.returned, %amount% is how many were given back. |
| %items\_word% | "item" or "items", to match the count. |
| %money% | What the sale paid, one total per currency. |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/selling/sell-feedback

---

# 📥 Sell Menu

> **Info:**
The menu's layout is menus/&lt;shop&gt;/sell-menu.yml, taken from the first whitelisted shop the player can open.

## Sell Menu

`/sell menu` opens a chest the player fills with the items they want to sell. Items the whitelisted shops do not buy are refused as they are put in, with the refused sound, so nothing the shops cannot pay for ever sits in the menu.

A shulker box is accepted when something inside it can be sold, while [Sell Shulker Contents](sell-command.md#shulker-boxes) is on.

Items go in by dragging, shift-clicking from the inventory, the hotbar number keys, or the swap-hands key for the off-hand item.

## Drop Slots

The slots items can be put in. By default these are the top five rows, with the bottom row kept for the border and the confirm button. Any slot that is not a drop slot is locked.

## Sell Items

The confirm button. Its lore shows what everything in the drop slots is worth, updated as items go in, and clicking it sells them and closes the menu.

Anything that could not be sold, such as a stack left over after selling in lots, goes back to the player's inventory, or is dropped at their feet if the inventory is full.

## Sell on Close

Whether closing the menu sells what is in it, the same as clicking Sell Items. On by default. When off, closing the menu without clicking Sell Items gives every item back.

This is only set in config.yml. While it is on, the Sell Items lore adds a line telling players that closing sells too.

> **Info:**
Bedrock players get a form instead of the chest while Bedrock sell forms are on. It lists every item in their inventory the shops buy, each with a toggle, and sells the ones left on.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/selling/sell-menu

---

# 📋 Whitelisted Shops

## Whitelisted Shops

The list of shops `/sell` and the sell menu may sell into, in priority order. Only the shop called `shop` is on it by default, so a new shop is left out of `/sell` until you add it.

<figure><img src="../../.gitbook/assets/whitelisted-shops/whitelisted-shops.png" alt="" width="563"><figcaption><p>Sell Command (Whitelisted Shops)</p></figcaption></figure>

A player only sells into the shops on the list they are allowed to open, and a disabled shop is skipped. When none are left for a player, `/sell` tells them there is no shop to sell to.

## Priority

When more than one listed shop buys the same item, the one highest on the list gets it. Put a VIP shop with better prices above the regular one, and give it a permission: VIP players sell at the better price, and everyone else falls through to the regular shop.

<figure><img src="../../.gitbook/assets/whitelisted-shops/priority.png" alt="" width="563"><figcaption><p>Whitelisted Shops (Priority Reordering)</p></figcaption></figure>

**Add Shop** puts a shop at the bottom of the list, and left-clicking a listed shop removes it. To change the order, turn on **Priority Reordering** and click two shops to swap their places.

## Shop No Longer There

A shop that was deleted stays on the list, marked as missing, until you remove it. It is simply skipped when selling.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/selling/whitelisted-shops

---

# 🏪 Shops

> **Info:**
Every shop is its own file in the shops folder, and its categories sit in a folder of the same name next to it.

## Add a Shop

Left-click the lime stained glass in **Editor > Shops** to create a shop. It is created with a generated identifier and its editor opens straight away, so rename it there.

<figure><img src="../../.gitbook/assets/shops/shops.png" alt="" width="563"><figcaption><p>Editor (Shops)</p></figcaption></figure>

<figure><img src="../../.gitbook/assets/shops/add-a-shop.png" alt="" width="563"><figcaption><p>Shops (New Shop)</p></figcaption></figure>

Every shop in the list shows its display name, its identifier and whether it is enabled. A shop priced in a currency whose plugin is not installed, by the shop itself or by any of its items, is marked in the list with the plugin to install. It still opens in the editor. Left-click one to edit it, right-click it to delete it after a confirmation.

> **Info:**
The Lite edition holds up to 3 shops. The button shows how many you have out of the limit and stops creating once it is reached. On startup, Lite loads only the first 3 shop files it finds and leaves the others untouched on disk. Unlimited shops are available with the Premium Plan.

## Navigation

| Features | Description |
| --- | --- |
| [Identifier](edit-shop.md#identifier) | The unique id of the shop and the name of its file. |
| [Display Name](edit-shop.md#display-name) | The name players see at the top of the shop. |
| [Open Command](edit-shop.md#open-command) | A command of its own that opens the shop. |
| [Conditions](edit-shop.md#conditions) | Who can open the shop. |
| [Rotations](edit-shop.md#rotations) | The categories of the shop that rotate. |
| [Currency](edit-shop.md#currency) | What everything in the shop is priced in. |
| [Currency Format](edit-shop.md#currency-format) | How prices in the shop are written. |
| [Categories](../categories/) | The categories of the shop. |
| [Enabled](edit-shop.md#enabled) | Turn the shop on or off. |
| [Edit Menus](edit-shop.md#edit-menus) | The layout of every menu the shop opens. |
| [Actions](edit-shop.md#actions) | What runs on a purchase, a sale, a refusal, a click or a page turn. |
| [Delete](edit-shop.md#delete) | Delete the shop. |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/shops

---

# 🖌️ Edit Shop

> **Info:**
Every option on this page is saved to the shop's own file in the shops folder.

## Identifier

The unique id of the shop, used in commands such as `/pshop open` and as the name of its file and category folder. Spaces are not allowed, and two shops cannot share one. Renaming moves the file and the folder, and the /sell shop list follows the new id.

<figure><img src="../../.gitbook/assets/shops/identifier.png" alt="" width="563"><figcaption><p>Edit Shop (Identifier)</p></figcaption></figure>

> **Danger:**
Stock counts are stored against the shop's identifier. Changing it starts the stock of every item in the shop over.

## Display Name

The name players see at the top of the shop. Color codes are supported. It cannot be empty.

<figure><img src="../../.gitbook/assets/shops/display-name.png" alt="" width="563"><figcaption><p>Edit Shop (Display Name)</p></figcaption></figure>

## Open Command

A command of its own that opens this shop, without the slash, such as `shop` or `blocks`. Leave it empty for no command. A command another plugin already owns is not taken over. A new or changed command works straight away, after the edit or a `/pshop reload`, with no restart and no rejoin.

<figure><img src="../../.gitbook/assets/shops/open-command.png" alt="" width="563"><figcaption><p>Edit Shop (Open Command)</p></figcaption></figure>

## Conditions

Who can open this shop. With no conditions, everyone can.

<figure><img src="../../.gitbook/assets/shops/conditions.png" alt="" width="563"><figcaption><p>Edit Shop (Conditions)</p></figcaption></figure>

On Premium this opens a list of checks built the same way as [item requirements](../items/requirements.md), with eight types: **permission**, **compare** for a PlaceholderAPI value, **world**, **gamemode**, **platform** (Java or Bedrock), **region** for a [WorldGuard](https://enginehub.org/worldguard) region the player stands in, **world-time** for the time of day in the player's world and **playtime**. Region only shows when WorldGuard is installed, and a region check without it refuses everyone. Minimum sets how many checks have to pass, each check can be negated, and its deny actions run when a player is turned away. On Lite this is a single permission field.

The conditions decide who can open the shop, and also which shops `/sell`, sell wands, AutoSell and `/pshop search` use for that player. A player turned away sees the shop-locked message, unless a failed check has deny actions of its own.

## Rotations

The categories of this shop that show only some of their items at a time. Left-click a rotation to edit it, right-click to stop it, and use **Make a Category Rotate** to pick another category of this shop. Needs the [Rotating Shop](../../add-ons/rotating-shop/) add-on.

## Currency

What everything in this shop is priced in. A category or an item can override it on Premium, see [Edit Category](../categories/edit-category.md#currency) and [Edit Item](../items/edit-item.md#currency).

<figure><img src="../../.gitbook/assets/shops/currency.png" alt="" width="563"><figcaption><p>Edit Shop (Currency)</p></figcaption></figure>

Left-click swaps between the currency types, skipping any whose plugin is not installed. Right-click opens the chosen type, where the Currency option opens a searchable list to pick from (ExcellentEconomy and PhoenixCurrencies), the Placeholder currency is opened to edit, an item is dropped in and its name, lore and Currency Display are set (Item), and the [Currency Format](#currency-format) is set for every type but Item.

Every type, what it needs and which edition has it is listed on [Currencies](../currencies/).

> **Warning:**
A shop whose currency cannot be used, because its plugin is not installed or the currency no longer exists, does not open at all. The editor marks the field with the plugin to install.

## Currency Format

How prices in this shop are written, such as `%amount% PlayerPoints` or `$%amount%`, with `%amount%` where the number goes, or `%amount_short%` for a short form such as `1.5k`. Leave it empty to use the currency's own format, see [Symbols and Formats](../currencies/README.md#symbols-and-formats). It is set from the right-click menu of the [Currency](#currency) option and applies to every price in the shop, including items that use another currency, except in categories that set a [format of their own](../categories/edit-category.md#currency-format).

## Categories

Opens the categories of this shop. See [Categories](../categories/).

<figure><img src="../../.gitbook/assets/shops/categories.png" alt="" width="563"><figcaption><p>Edit Shop (Categories)</p></figcaption></figure>

## Enabled

A disabled shop keeps its configuration but cannot be opened by anyone.

<figure><img src="../../.gitbook/assets/shops/enabled.png" alt="" width="563"><figcaption><p>Edit Shop (Enabled)</p></figcaption></figure>

## Sale

Premium. Puts every item in the shop on sale, with the same options as a [category sale](../categories/edit-category.md#sale): the discount, a start and end date and time, days of the week, a daily time window and the Start and Stop button. A category whose own sale is running uses that one instead, so a category can run a different deal during a shop-wide sale.

<figure><img src="../../.gitbook/assets/shops/sale.png" alt="" width="563"><figcaption><p>Edit Shop (Sale)</p></figcaption></figure>

## Edit Menus

Opens the list of every menu this shop uses: the main menu, the buy and sell menus, the bulk buy and bulk sell menus, the sell menu, the confirm menu and one menu per category. The Filter button shows only the shop menus or only the category menus. Left-click one to edit its layout in-game. While you edit, the menu shows its real title and your hotbar holds the editor tools.

<figure><img src="../../.gitbook/assets/shops/edit-menus.png" alt="" width="563"><figcaption><p>Edit Shop (Edit Menus)</p></figcaption></figure>

## Actions

Lists of [actions](../../plugin-information/action-types.md) run at moments in this shop, such as a sound, a message, a title or a command: Buy and Sell when a purchase or sale goes through, Deny when one is refused, Click when a category or item is clicked, Previous Page and Next Page when the pages are turned, Add and Remove when the amount buttons of the buy and sell menu raise or lower the amount, Fill when the fill button sets the most you can buy or sell, and Back when a menu's back button is clicked. Each list starts with a single sound. Empty a list to run nothing.

<figure><img src="../../.gitbook/assets/shops/actions.png" alt="" width="563"><figcaption><p>Edit Shop (Actions)</p></figcaption></figure>

`%player%` is filled in everywhere. In Buy, Sell and Deny, `%item%`, `%amount%`, `%price%`, `%currency%` and `%balance%` are filled in as well, and in Click on an item, `%item%`.

Inside a category, its own [actions](../categories/edit-category.md#actions) replace Buy, Sell, Deny, Click and the page lists when they are not empty. The shop's main menu always runs the shop's lists.

> **Info:**
The editor screen is only available with the Premium Plan. On Lite the lists run the same way and are edited in the [shop file](../../configurations/shop-configuration-file.md#shop-file).

## Delete

Deletes the shop together with its file, its categories and their items, after a confirmation.

<figure><img src="../../.gitbook/assets/shops/delete.png" alt="" width="563"><figcaption><p>Edit Shop (Delete)</p></figcaption></figure>

> **Danger:**
This option is permanent, and shops can't be restored.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/main-features/shops/edit-shop

---

# 🚢 Migration

## Migration

Our plugin can bring your shops across from other shop plugins, and from some of them the player data too. Below are the available migration options.

* **ShopGUIPlus**
* **EconomyShopGUI** (free and Premium, shops plus stock, limits and purchase history)
* **UltimateShop**
* **ExcellentShop**
* **Essentials** (worth.yml)
* **QuickShop** (Hikari and Reremake, chest shops, as player shops)
* **Shop (snowgears)** (chest shops, as player shops)
* **ChestShop** (sign shops, as player shops)

The three chest shop migrations bring every player's shops across on Lite too, even past the 25 chest shops (30 on a linked server) a player can own there. Imported shops always load, and they count toward the limit, so a player at or over it cannot make another until they are below it. When a migration leaves players over the limit, the chat says how many, and a file in migrations/ lists each of them with how many shops they own.

## Running a Migration

Open **Editor > Migrations**. There is one button per plugin, listing the files it reads and whether player data comes across. A button is locked when those files are not in your plugins folder, so the other plugin's folder has to be there, but the plugin itself does not need to be running.

<figure><img src=".gitbook/assets/migrations/migrations.png" alt="" width="563"><figcaption><p>Editor (Migrations)</p></figcaption></figure>

1. Click the plugin to read its files and database. Nothing is written yet.
2. A confirmation opens, showing how many shops, categories, items, past transactions and limit counts were found. Confirm to write, or cancel to leave everything as it was.
3. The menu closes and the chat says when the migration has finished, and how many entries came from the old plugin's database. When the old plugin is still running, a second line asks you to remove it, since it would keep answering the same commands and signs.

Before anything is written, the whole plugin folder is copied to backups/, the SQLite database included. If the copy fails, nothing is written. The new shops are live straight away.

### Note

* Every plugin comes across as one shop opened with `/shop`, with one category per shop or section of the old plugin. `/shop <category>` opens a category directly, as it did before. If one of your shops already uses `/shop`, the import gets no command; give it one in the editor.
* Each category is named, described and iconed the way its button looked in the old main menu, head textures and custom model data included, and keeps that button's order.
* A shop's identifier that is already taken is skipped, never overwritten. Rename or delete yours first to import over it. Player data for a skipped shop is skipped with it.
* Every entry that is left out is named with its file in migrations/, one file per plugin. The chat only says the migration finished, and points to that file when something did not come across.
* An item that cannot be read is left out and reported, and the rest of the import still comes across. Items newer than the plugin's material list import as long as the server knows them.
* Items come across in the order players saw them, page by page and slot by slot where the old plugin set them, otherwise in the order of the file. The exact slots and pages are not kept.
* An item that is bought for itself gives that item, with its name, lore and amount, the same as an item dropped on the editor. When the old plugin showed one item and handed out another, the shop shows the first and gives the second. Command, permission and link entries only run their commands.
* Items that carry a potion type, stored enchantments, a spawner mob, a head texture or custom model data are only bought back when the held item matches exactly, so a plain water bottle cannot be sold as a potion.
* Colours written as `#RRGGBB`, `{#RRGGBB}` or as a gradient pair are turned into the forms this plugin reads.
* The Lite edition holds 3 shops, and the default shop already counts. When the import would go past that, a menu lists the imported shops with the categories each one brings, and you pick as many as there are free slots. They are added next to your shops. When all 3 slots are taken, the import stops and asks you to delete a shop first; it never replaces one. Categories are not limited, so a whole import fits in one shop.
* On Lite, whatever needs Premium is left out, and the report says so for each one: currencies per category or item, item and placeholder currencies, requirements, conditions other than a permission, stock, limits, restocks, opening hours, category actions and sales, price modifiers, Sell Boosters entries and rotating sections, which show every item, chest shop staff, and chest shops paid in an item. A shop priced in an item currency is priced in money instead. Past transactions come across.
* Stock and per-player limit counts are left out with the Network add-on, since it keeps stock in its own tables.
* Past transactions older than the history keeps are left out, see the history setting in config.yml.
* An item from another plugin, such as ItemsAdder or Nexo, is kept, and only shows once that plugin is installed.
* A chest shop in a chunk that is not loaded during the import is imported anyway and checked when its chunk loads: its sign is rewritten to ours then, and a shop whose sign or container is gone is removed.

## ShopGUIPlus

Reads every shop in ShopGUIPlus/shops, the older single shops.yml, and the main menu in config.yml. A shop with a main-menu button is a category on the main menu. A shop that is only reached from another shop, through a link or a decoration that runs `/shopgui <shop>`, opens from that shop as a sub-category, looking like the button that led to it. A shop reached from neither is hidden and opens with `/shop <shop>`.

<figure><img src=".gitbook/assets/migrations/shopguiplus.png" alt="" width="563"><figcaption><p>Migrations (Migrate from ShopGUIPlus)</p></figcaption></figure>

Menu titles drawn with a resource pack font are not used as names, since they mean nothing in these menus.

| ShopGUI+ entry | Becomes |
| --- | --- |
| `item` | An item, with its amount, prices, name, lore, enchantments, item flags, custom model data, glow, spawner mob, armor trim, potion type, leather colour, banner patterns, goat horn sound and head texture. Its `placeholder` is what the shop shows. Items from ItemsAdder, Nexo, CraftEngine, HeadDatabase, ExecutableItems, Slimefun, MMOItems and MythicMobs keep their plugin item. |
| `command` | A buy-only item that runs the same commands, as the buyer when it ran as the buyer. Its command limit becomes the most per purchase. |
| `shop_link` | The linked shop opens from this one as a sub-category. A link to a shop that has its own main-menu button is left out. |
| `permission` | An item whose purchase gives each node with a LuckPerms command, and whose sale removes them. A node limited to one world is given in that world only. A requirement stops players buying a node they already have. |
| `enchantment` | A buy-only item that runs the vanilla `/enchant` command on the held item. A requirement stops the purchase unless the player holds something the enchantment can go on. |

Shop and item `messageBuy`, `messageSell` and `messageCannotAfford` become the messages of the category and item. Fireworks and unbreakable items come across as the exact item when the import runs on the server. A command entry without `runSingleCommand` ran once per item bought, so it is bought one at a time here. The click actions of the main config and of each shop become the category's click mappings, and a shop with its buy or sell screen turned off buys or sells one at a time on click. Extra buy and sell commands come across as purchase and sell commands, and required permissions as requirements. A shop's permission, per-item permissions and world blacklist become conditions. The shop's economy is mapped onto our currencies: Vault, PlayerPoints, VotingPlugin and Experience, with `EXP` as experience points and `EXP_LEVELS` as levels, so prices keep their value. Names and lore are only compared on a sale when `compareMeta` was on. An entry with a buy price of 0 becomes a [free](main-features/items/edit-item.md#free) item.

ShopGUI+ keeps no stock or limits. Player data comes across as follows:

| Data | Becomes |
| --- | --- |
| Transaction log (shop.log) | Past purchases and sales in the purchase history, read with the log and date formats from its config.yml. Command, permission and enchantment purchases are left out. |
| Players in its database, SQLite or MySQL as set in its config.yml | Used to tie each logged name to its player. |
| Global permission price modifiers (pricemodifiers.yml) | [Price modifiers](add-ons/sell-boosters/README.md#price-modifiers) in the Sell Boosters add-on, with the same `shopguiplus.pricemodifiers.<id>` permission, so players keep them without changes. Without the add-on they are reported. |
| Permission price modifiers for one shop or item | Their sell side becomes a [permission booster](add-ons/sell-boosters/README.md#permission-boosters) in the Sell Boosters add-on, with the same permission. Their buy side is left out. Without the add-on they are reported. |
| Per-player price modifiers set with its commands | Left out and counted in the report. Players left at the default are not counted. |

> **Warning:**
Permission entries assume LuckPerms. On another permissions plugin, change their purchase and sell commands after importing. The requirements on permission and enchantment entries only run on Premium.

## EconomyShopGUI

Reads EconomyShopGUI-Premium when it is there, otherwise EconomyShopGUI: the shop and section files, including those in sub-folders, or the older single shops.yml and sections.yml. Everything becomes one shop called `economyshopgui`, with one category per section. A sub-section opens from the section that links to it, named, iconed and ordered like the link button. A hidden section opens with `/shop <section>`. A section's click commands run when its category opens. A section that only decorates the main menu is left out.

<figure><img src=".gitbook/assets/migrations/economyshopgui.png" alt="" width="563"><figcaption><p>Migrations (Migrate from EconomyShopGUI)</p></figcaption></figure>

Items keep their amount, prices, currency, name, lore, enchantments, item flags, custom model data, glow, spawner mob, armor trim, potion types, goat horn sound, leather colour, head texture, most per purchase and least per sale. `displayname` and `displaylore` are what the shop shows, and `name` and `lore` go on the item the player gets. A `display-item` is what the shop shows while the player gets the item itself. `fixed-stack-size` works like `stack-size`. Plugin items keep their plugin item, except Oraxen, Brewery and EcoItems. Buy and sell commands come across, and items that also gave the item still give it. Delayed commands run straight away, and commands run with temporary OP run as the player. Prices in an `ITEM` economy, or in `buy-prices` and `sell-prices`, become an item currency on Premium. One with a `name` or `id` becomes a currency of its own under that name, and a `name` only accepts the item with that name. With several prices, the first one is kept. A negative price turns that side off, and a buy price of 0 makes the item [free](main-features/items/edit-item.md#free).

Fireworks, suspicious stews, ominous bottles, knowledge books, unbreakable items and `components` come across as the exact item when the import runs on the server. Custom model data is read from `CustomModelData`, `NBTData` and `components`.

| EconomyShopGUI option | Becomes |
| --- | --- |
| `permission` | A requirement on `EconomyShopGUI.shop.<section>.item.<permission>`. With `permission-requirement: false`, only players without it can buy. |
| `requirements` | `PERMISSION`, `LEVEL`, `REGION`, `PLACEHOLDER`, `TIME`, `PLAYTIME` and `ITEM` lines become requirements, with their denied message. `TIME` checks the time of day in the player's world, and `ITEM` the item's material and name anywhere in the inventory. `QUEST` lines are left out. Level and placeholder checks need PlaceholderAPI. |
| `level-requirement` | A requirement on the player's level. |
| `click-mappings` | The category's click actions, from the section or from config.yml. |
| `damaged-items` | Damaged items sell for their price times the durability left. `price-difference` is left out. |
| `max-buy: -1`, `max-sell`, `min-buy`, `hidePricingLore`, `close-menu`, item `click-commands`, `if-not-met` | Left out and reported. |

| EconomyShopGUI limit | Becomes |
| --- | --- |
| Global stock | Stock. Selling an item always puts it back in stock here, as `refill-stock: true` did. |
| Player stock | Player limit. |
| Player sell limit | Sell limit. |
| Restock timer or schedule | Restock. One clock refills an item here, so an item with several keeps the first. A per-player timer becomes one shared clock. |
| Global sell limit | Left out. |
| Dynamic pricing | Left out, the base price is kept. |

Premium also brings the player data across, from its SQLite database or from MySQL with the connection and table prefix in its config.yml:

| Data | Becomes |
| --- | --- |
| Stock left on each item | Stock left. |
| Each player's buys and sells within their limits | The same counts against our limits. |
| Advanced transaction log | Past transactions in the purchase history. A sale of several items at once is split per item. |
| Global sell limit counts, dynamic pricing state, per-player price modifiers | Left out and counted in the report. |

Discounts and sell multipliers in its config.yml come across when they are turned on. Those under `all` become [price modifiers](add-ons/sell-boosters/README.md#price-modifiers) in the Sell Boosters add-on with the same `EconomyShopGUI.discounts.<group>` or `EconomyShopGUI.sell-multipliers.<group>` permission. A sell multiplier for one section becomes a [permission booster](add-ons/sell-boosters/README.md#permission-boosters) on that category. A discount for one section is left out.

A rotating section becomes a [rotating category](add-ons/rotating-shop/README.md#rotation) with its whole pool when the Rotating Shop add-on is installed, otherwise a normal category that shows every item. `frequency` becomes a cron schedule and wins over `interval`, which becomes a length; with neither it changes daily. `can-repeat`, `broadcast` and each item's `display-chance` are kept. It shows as many items as it had display slots across its pages, in the order of the category, so the slot positions are not kept.

Counts and transactions for items that are no longer in the shop files are left out. The plain text transaction log is not read.

## UltimateShop

Reads UltimateShop/shops, the main menu in menus/main.yml, and the language files for every `{lang:...}` reference. Everything becomes one shop called `ultimateshop`. A shop file's next-page button folds the next file into the same category.

<figure><img src=".gitbook/assets/migrations/ultimateshop.png" alt="" width="563"><figcaption><p>Migrations (Migrate from UltimateShop)</p></figcaption></figure>

Items keep their product, amount, name, lore, enchantments, stored enchantments, potion type and effects, head texture, leather colour, banner patterns, spawner mob, armor trim, item model and prices, including the shared prices and the general settings of the file. Its `display-item` is what the shop shows and its product what the player gets. Its `add-lore` lines are added to the shown lore. Buy, sell and give actions that run commands come across as commands, and a product with give actions is still given unless it has `give-item: false`. Such a product sells back only as the exact item. Permission conditions on the shop, the file or the item become conditions and requirements. Slots from the menu layout are not kept.

A `match-item` rule that only lists materials sells as the product's material, or the first listed, and `has-name: false` also requires an unnamed item. Any other rule, or a product that is no item at all, leaves the item buy-only. When an item lists several products or prices, the first money price is taken. In `ALL` and `CLASSIC_ALL` price modes, plain prices in one currency are added up; otherwise one is kept and the report says the item is cheaper now. Shared prices from its config.yml are resolved. A price paid in a plain item becomes an item currency on Premium. Prices written as a formula, paid in plugin items, or paid through a placeholder or commands are left out. A buy price of 0, or one that names nothing to pay, makes the item [free](main-features/items/edit-item.md#free). `exp` prices stay experience points and `levels` prices levels. CoinsEngine and ExcellentEconomy currencies keep their currency, other economy plugins are left on the shop's currency.

A global buy limit becomes stock, the default buy and sell limits become per-player limits, and `-1` stays unlimited. Products in one `shared-use-times` group get that group's limits and become one limit group, each with its own stock. A timed reset becomes a daily restock at its first time, or a restock that many days after selling out when it sets days. A timer reset becomes one shared refill clock, a cron reset its schedule, and the default reset in config.yml applies to items without one. Limits that depend on a condition are left out. How much each player has already bought and sold, and how much of the global stock is used, come across from its player data files or its database.

## ExcellentShop

Reads the virtual shops in ExcellentShop/virtual_shop/shops, both the single-file and the older folder layout, with nightcore's colour scheme and currencies. Everything becomes one shop called `excellentshop`. Each shop's main-menu icon name and description name its category, its main-menu slot orders it, its first alias becomes the category's command, and a required permission becomes `excellentshop.virtual.shop.<shop>`. A shop that turned buying or selling off keeps it off.

<figure><img src=".gitbook/assets/migrations/excellentshop.png" alt="" width="563"><figcaption><p>Migrations (Migrate from ExcellentShop)</p></figcaption></figure>

Products come across as the exact item, with every detail of the stack, and keep their prices and currency. nightcore colour names such as `<soft_green>` keep the colour they had on that server. Command products run their commands, `player:` ones as the player, and once per purchase unless they use `%amount%`. Items from Nexo, ItemsAdder, MMOItems, CraftEngine and ExecutableItems keep their plugin item. Required and forbidden permissions and ranks become requirements. Dynamic prices come across as their starting price, floating ones as the middle of their range. Global stock and per-player buy and sell limits come across with their restock time. The remaining stock and each player's purchases and sales in data.db come across too. Rotating products are left out, see the Rotating Shop add-on for those. Chest shops and the auction house are not read at all.

## QuickShop

Reads QuickShop-Hikari when it is there, otherwise the older QuickShop (Reremake), from its local database or from MySQL with the connection and table prefix in its config.yml. Each shop becomes a [player shop](main-features/player-shops/README.md) on the same container and sign, owned by the same player, and its sign is rewritten to ours. A shop whose sign or container already holds one of ours is left alone, so importing again only adds what is missing.

<figure><img src=".gitbook/assets/migrations/quickshop.png" alt="" width="563"><figcaption><p>Migrations (Migrate from QuickShop)</p></figcaption></figure>

| QuickShop shop | Becomes |
| --- | --- |
| Selling | Players buy from the chest, at the same price. |
| Buying | Players sell into the chest. |
| Frozen | Left out. Unfreeze it and import again. |
| Unlimited | An admin shop with endless stock, paying nobody. |
| Owned by the server | An admin shop when unlimited, otherwise left out. |

The item comes across as the exact stack. With stacking shops turned off, a shop trades one item at a time, as it did. Staff and administrators of a shop become its staff. A currency that is also set up here keeps that currency, any other becomes money. A shop with its display item turned off keeps it off. Shop names, profit sharing, blocked players and per-shop tax accounts are left out and counted in the report.

QuickShop-Hikari keeps its shops in an H2 database. Reading it needs the H2 driver, which is downloaded from Maven Central into libs/ the first time and checked against its published checksum. On a server without internet access, put `h2-2.1.214.jar` from Maven Central in that folder yourself. The database is copied before it is read, never opened in place. On Windows, QuickShop-Hikari locks it while running, so remove its jar and restart before importing there.

The sign is the empty or QuickShop sign on a side of the container, as QuickShop finds it. A shop in an unloaded chunk takes the first wall sign on its container when that chunk loads. Shops with no sign, or on any container other than a chest, trapped chest, barrel or shulker box, are left out. Purchase logs and offline notifications are not read.

## Shop (snowgears)

Reads every owner's shop file in Shop/Data, the admin shops and the older files named after the player, with the currency from its config.yml. Each shop becomes a [player shop](main-features/player-shops/README.md) on the same sign and container, owned by the same player. Signs in loaded chunks are rewritten to ours. A sign that already holds one of ours is left alone, so importing again only adds what is missing.

<figure><img src=".gitbook/assets/migrations/shop-snowgears.png" alt="" width="563"><figcaption><p>Migrations (Migrate from Shop (snowgears))</p></figcaption></figure>

| Shop type | Becomes |
| --- | --- |
| `sell` | Players buy from the chest, at the same price for the same amount. |
| `buy` | Players sell into the chest. |
| `combo` | Both. The sell price is what players pay, the buy price what they get. |
| `barter` | Players buy, paying with the barter item. |
| `gamble` | Left out. |
| Admin shops | Admin shops with endless stock and no owner. |

A `VAULT` currency becomes money and `EXPERIENCE` becomes experience points. An `ITEM` currency, the default, makes every shop paid in that item, emerald unless it was changed, with prices as item counts. A trade amount above a stack comes across as it was. Display type `NONE` turns the shop's display off.

Shops on an ender chest or any other container than a chest, trapped chest, barrel or shulker box are left out. Offline purchase notifications and its transaction database are not read.

## ChestShop

ChestShop keeps its shops only on the signs, so the import reads the saved region files of every loaded world, without loading a chunk. Run `/save-all` first, or shops made since the last save are missed. Each sign becomes a [player shop](main-features/player-shops/README.md) on the same sign and the container ChestShop trades from, owned by the player its users.db names for the sign. A sign that already holds one of ours is left alone, so importing again only adds what is missing.

<figure><img src=".gitbook/assets/migrations/chestshop.png" alt="" width="563"><figcaption><p>Migrations (Migrate from ChestShop)</p></figcaption></figure>

| Sign | Becomes |
| --- | --- |
| `B` price | Players buy from the chest, at that price for the sign's amount. |
| `S` price | Players sell into the chest. |
| Both | Both, each at its own price. |
| `free` | A price of 0. |
| Amount above a stack, or a stock counter | The same amount. The counter is dropped. |
| Item name, shortened name, `:damage` or `#code` | The exact item, `#code` items with every detail from its items.db. Item aliases are followed. |
| Admin Shop | An admin shop with endless stock, even where it traded from its chest before. |

A container here holds one shop, so when several signs trade from one chest only the first comes across. Admin Shop signs with no chest beside them become admin shops that need no container. Signs whose owner its users.db does not know, unfinished `?` signs, and shops on a container other than a chest, trapped chest, barrel or shulker box are left out. Players who turned off their sale messages keep them off. Discounts, price limits and tax are not read.

## Essentials

Reads Essentials/worth.yml, and items.json for older item names. Everything becomes one sell-only shop called `essentials`, sorted into Tools, Armour, Ores, Food, Blocks and Other categories. When two entries name the same item, the one under its current name wins. Prices split by data value price each old variant, such as each sapling, and the `*` price covers the variants with none of their own. Entries that are not an item a player can hold, such as water and lava, are left out.

<figure><img src=".gitbook/assets/migrations/essentials.png" alt="" width="563"><figcaption><p>Migrations (Migrate from Essentials)</p></figcaption></figure>

Source: https://www.phoenixplugins.com/docs/phoenix-shop/migration

---

# 🤖 Action Types

In our system's configuration files, you can utilize various action types to perform different actions. These actions enable you to interact with players, send messages, play sounds, set gamemodes, and much more.

Actions run from four places:

* **Menu buttons**, from the actions of any button in a shop menu.
* **Shop actions**, when a player buys, sells, is refused, clicks, turns a page or uses the amount, fill and back buttons in a shop.
* **Category actions** ⭐, when a player opens or closes a category.
* **Deny actions** ⭐, when a requirement stops a player from buying or selling an item.

## Action Types

| Action Type | Description | Where |
| ----------- | ----------- | ----- |
| \[ACTION\_BAR] | Display a custom action bar to the player | Everywhere |
| \[CLOSE\_INVENTORY] | Close the player's current inventory | Everywhere |
| \[SOUND] | Play a sound for the player | Everywhere |
| \[TITLE] | Display a custom title message to the player | Everywhere |
| \[DELAY] | A way to delay some actions | Everywhere |
| \[MESSAGE] ⭐ | Display a custom message to the player | Everywhere |
| \[COMMAND] ⭐ | Execute a command (console or player) | Everywhere |
| \[GAMEMODE] ⭐ | Set the player's gamemode | Everywhere |
| \[PARTICLE] ⭐ | Show particles around the player | Everywhere |
| \[CATEGORY] | Open a category | Everywhere |
| \[SHOP] | Open a shop's main menu | Everywhere |
| \[ENCHANT] ⭐ | Enchant the item in the player's hand | Deny actions |
| \[PERMISSION] ⭐ | Give or take a permission | Deny actions |

Explore each action type to learn more about its syntax and usage. Examples are provided to illustrate how to use these actions effectively in your system or application.

> **Info:**
The actions do not replace any placeholder themselves. In a menu button, the menu's own placeholders are filled in before the action runs, so a button in a category can use `%player%`. See [Placeholders](placeholders.md#menu-placeholders).

## **Send Action Bar Message**

This action displays a custom action bar message to the player.

* **Syntax:** `[ACTION_BAR] <message>`
* **Example:** `[ACTION_BAR] &aThanks for shopping`

## **Close Inventory**

This action closes the inventory the player has open.

* **Syntax:** `[CLOSE_INVENTORY]`
* **Example:** `[CLOSE_INVENTORY]`

## **Play Sound**

This action plays a sound for the player.

* **Syntax:** `[SOUND] <sound>; <volume>; <pitch>`
* **Example:** `[SOUND] entity_experience_orb_pickup; 1; 1`

## **Send Title Message**

This action displays a custom title message to the player. The timings are in ticks.

* **Syntax:** `[TITLE] <title>; <subtitle>; <fadein>; <stay>; <fadeout>`
* **Example:** `[TITLE] &aCustom title; &7Custom Subtitle; 20; 40; 20`

## **Delay**

This action will make a short pause until it continues executing actions.

* **Syntax:** `[DELAY] <seconds>`
* **Example:** `[DELAY] 3`
* **Example:** `[DELAY] 0.5`

## **Open a Category**

This action opens a category for the player, with the same checks as clicking it in the main menu: the shop's and the category's conditions apply and a disabled category does not open. A [hidden](../main-features/categories/edit-category.md#hidden) category opens.

* **Syntax:** `[CATEGORY] <category>` or `[CATEGORY] <shop>:<category>`
* **Example:** `[CATEGORY] ores`
* **Example:** `[CATEGORY] blocks:wool`

Without a shop, the category is looked up in the shop the action runs in. Outside a shop menu, such as in a deny action, write the shop as well.

## **Open a Shop**

This action opens a shop's main menu for the player, with the same checks as its open command.

* **Syntax:** `[SHOP] <shop>`
* **Example:** `[SHOP] blocks`

## **Send Chat Message** ⭐

This action sends a custom message to the player.

* **Syntax:** `[MESSAGE] <message>`
* **Example:** `[MESSAGE] &aThis is a custom message`

Semicolons inside the message are kept, so you do not have to escape them.

## **Execute Command** ⭐

This action executes a command either from the console or as a player.

* **Syntax:** `[COMMAND] <target>; <command>`
* **Example:** `[COMMAND] console; give %player% diamond 1`
* **Example:** `[COMMAND] player; spawn`

The target has to be either `console` or `player`. A leading `/` is optional.

## **Change Gamemode** ⭐

This action sets the gamemode for the player.

* **Syntax:** `[GAMEMODE] <gamemode>`
* **Example:** `[GAMEMODE] adventure`

## **Show Particles** ⭐

This action spawns particles at the player's location, seen only by that player.

* **Syntax:** `[PARTICLE] <particle>; <count>; <offset x>; <offset y>; <offset z>`
* **Example:** `[PARTICLE] happy_villager; 20; 0.5; 1; 0.5`

Particles that need a color, a block or an item, such as dust, are skipped.

## **Enchant Held Item** ⭐

This action adds an enchantment to the item in the player's main hand. Nothing happens when the hand is empty.

* **Syntax:** `[ENCHANT] <enchantment>; <level>`
* **Example:** `[ENCHANT] sharpness; 5`

## **Give or Take a Permission** ⭐

This action gives the player a permission, or takes it away when `remove` is added. It needs Vault and a permissions plugin hooked into Vault.

* **Syntax:** `[PERMISSION] <permission>; [remove]`
* **Example:** `[PERMISSION] essentials.fly`
* **Example:** `[PERMISSION] essentials.fly; remove`

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/action-types

---

# 🤖 Commands

## Commands

The following list shows all available commands for the plugin.

**Command alias:** `/phoenixshop`, `/phoenixs`, `/pshop`

<> - Required \
\[] - Optional

**Player Commands**

| Command | Description |
| ------- | ----------- |
| `/<shop command> [player]` | Opens that shop, such as `/shop`. |
| `/pshop open <shop> [category] [player]` | Opens a shop, or one of its categories. |
| `/pshop buy <shop> <category> <item> [amount]` | Buys an item without opening the shop. |
| `/pshop sell <shop> <category> <item> [amount]` | Sells an item without opening the shop. |
| `/sell hand` | Sells the item in your hand. |
| `/sell handall` | Sells every stack identical to the item in your hand. |
| `/sell inventory` | Sells everything in your inventory. |
| `/sell menu` | Opens the sell menu. |
| `/pshop search [terms]` ⭐ | Searches for an item across every shop. |
| `/pshop search hand` ⭐ | Searches every shop for the item in your hand. |
| `/pshop undo` ⭐ | Reverses your last transaction. |
| `/pshop alerts toggle` ⭐ | Turns restock and sale alerts off or on. |
| `/pshop forms` | Switches between Bedrock forms and chest menus. |

**Admin Commands**

| Command | Description |
| ------- | ----------- |
| `/pshop editor` | Opens the in-game editor. |
| `/pshop editlayout <shop> <menu>` | Edits the layout of a shop menu in-game. |
| `/pshop reload` | Reloads config.yml, the shops and the menus from disk. |
| `/pshop changelog` | Opens the list of released builds and their changes. |
| `/pshop link` | Lite only. Links this server to your Phoenix Plugins account for 5 more chest shops per player. See [Linking a Lite Server](licensing.md#linking-a-lite-server). |
| `/pshop addons` ⭐ | Lists the official add-ons, green when installed and gray when not, then any third-party add-ons. Clicking an official add-on opens its page. |
| `/pshop history [player]` | Opens the purchase history. |
| `/pshop history export [player] [shop]` ⭐ | Exports the purchase history to the exports folder. |
| `/pshop prices` | Opens the price generator. |
| `/pshop audit` ⭐ | Looks for money loops in the prices. |
| `/pshop limits reset <player> [shop] [category] [item]` ⭐ | Resets a player's buy and sell limits. |
| `/pshop stock set <shop> <category> <item> <amount>` ⭐ | Sets how many of an item are left. |
| `/pshop stock restock <shop> <category> <item>` ⭐ | Restocks an item now. |
| `/pshop editshop` | Edits the Sign Shop or chest shop you are looking at. |
| `/pshop webhooktest` ⭐ | Posts a test message to the Discord webhooks. |

On Lite, `/pshop addons`, `/pshop audit`, `/pshop limits`, `/pshop stock` and `/pshop history export` reply with a link to the Premium page instead.

**Chest Shop Commands**

| Command | Description |
| ------- | ----------- |
| `/chestshop notifications` | Opens the menu that turns each kind of [owner notice](../main-features/player-shops/trading.md#owner-notices) about your shops on or off. |
| `/chestshop list [search]` | Lists every player shop, or those whose item, owner or name matches. Left-click an entry to teleport, right-click it to trade remotely. |
| `/chestshop price <buy\|sell> <price>` | Sets a price on the chest shop you are looking at. |
| `/chestshop amount <amount>` | Sets how many items the chest shop you are looking at trades per click. |
| `/chestshop mode <buy\|sell\|both>` | Sets the mode of the chest shop you are looking at. |
| `/chestshop name <name>` | Names the chest shop you are looking at, `-` clears it. |
| `/chestshop discount <percent> <length>` | Starts a timed discount on the chest shop you are looking at, `off` ends it. ⭐ |
| `/chestshop find [search] [selling\|buying]` | Opens a menu of the shops that sell and buy an item, found by its name, material or custom id. Without a search it uses the one in your hand. |
| `/chestshop market` | Opens the market: every traded item with its cheapest seller and best buyer. ⭐ |
| `/chestshop transfer <player>` | Hands the player shop you are looking at to another player. |
| `/chestshop tp [shop]` | Teleports to a chest shop, the same as clicking it in the list. Tab completion lists your own shops, by name with spaces as `_`, or by a short code for a shop without a name; admins get every shop. The **\[Teleport]** on an owner notice runs it. With no shop named, it goes to the shop of your latest stock warning. |
| `/chestshop transferall <from> <to>` | Moves every player shop of one player to another. |
| `/chestshop purge [days] [confirm]` | Counts, then with `confirm` removes, the player shops of owners who have not played for that many days. ⭐ |
| `/chestshop clean [confirm]` | Counts, then with `confirm` removes, the shops in loaded chunks that sell to players and hold less than one trade. |
| `/chestshop removeall <player> [confirm]` | Counts, then with `confirm` removes, every player shop that player owns. |
| `/chestshop ban <player>`, `/chestshop unban <player>` | Stops a player from making chest shops and trading at any chest shop, or lets them again. |
| `/chestshop removeworld <world> [confirm]` | Counts, then with `confirm` removes, every chest shop in that world, admin shops included. |

## Chest Shop Command

The player shop commands are under `/chestshop`, alias `/cs`. Both names can be changed, or the command turned off, in the commands section of config.yml, see [Chest Shop Command](../main-features/player-shops/settings.md#chest-shop-command). The details of each are on [Player Shops](../main-features/player-shops/README.md).

## Shop Commands

Every shop registers its own command, named after the shop's open command rather than its identifier, so renaming a shop does not move its command. Adding the player's name opens the shop for them, which needs `phoenixshop.command.open-others`.

If another plugin already owns that command, the shop gets none and the console says so. The shop is still reachable with `/pshop open <shop>`.

A category can have an [open command](../main-features/categories/edit-category.md#open-command) of its own in the same way. A command a shop already uses is not given to a category.

`/pshop open` works from the console as long as a player is named. When its second word is not a category of the shop but is an online player, the shop's main menu opens for that player, so `/pshop open <shop> <player>` keeps working.

## Quick Buy and Sell

`/pshop buy` and `/pshop sell` trade one item by its shop, category and item identifier, and tab complete each in turn. The `amount` is in items and is rounded down to whole lots, with at least one lot. Without it, one lot is traded.

Everything a trade in the menu checks still applies: the shop's conditions, requirements, stock, limits and prices, along with the messages and the shop and category actions. A disabled shop, category or item refuses.

The limits and stock commands are covered on [Stock & Restock](../main-features/items/stock-and-restock.md#commands), and the alerts command on [Restock & Sale Alerts](../features/restock-and-sale-alerts.md).

## Arguments

| Argument | Accepts |
| -------- | ------- |
| `<menu>` | `main`, `buy`, `sell`, `bulk-buy`, `bulk-sell`, `sell-menu`, or the identifier of one of the shop's categories. |
| `[player]` in history | A player name, or `*` for everyone. |

`/pshop forms` only works for Bedrock players, and only while Bedrock forms and the opt-out are both enabled in config.yml.

> **Info:**
`/sell` takes over the command from any other plugin that registered it first. That plugin's own command stays reachable with its prefix, such as `/essentials:sell`.

## Add-on Commands

The add-ons register commands of their own, documented on each add-on's page. Add-ons load on Premium only.

| Add-on | Commands |
| ------ | -------- |
| AutoSell | `/autosell`, `/pshop autosell`, `/pshop sellchest` |
| Rotating Shop ⭐ | `/rotatingshop`, `/rshop` |
| Sell Boosters ⭐ | `/sellbooster`, `/sellboosters` |
| Sell Wands ⭐ | `/sellwand`, `/sellwands` |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/commands

---

# 🪪 Lite and Premium

> **Info:**
License keys, sessions, startup validation and failures work the same for every Phoenix plugin and are covered on the general [Licensing](https://www.phoenixplugins.com/docs/phoenix-plugins/licensing) page.

Phoenix Shop comes in two jars. PhoenixShopLite is the free version and PhoenixShop is the Premium one. Both share the same editor, menus and file format, so everything built on Lite keeps working after an upgrade.

## What the Lite Version Limits

| Feature | Lite | Premium |
| --- | --- | --- |
| Shops | 3 | Unlimited |
| Currencies | Vault, PlayerPoints, VotingPlugin, ExcellentEconomy, PhoenixCurrencies, Levels | Adds Item and Placeholder |
| Currency per category and per item | No | Yes |
| Database | SQLite | SQLite, MySQL, MariaDB |
| Menu actions | Action Bar, Close Inventory, Sound, Title, Delay | Adds Command, Gamemode, Message, Particle |
| Stock, player limits and restocking | No | Yes |
| Requirements | No | Yes |
| Category open and close actions | No | Yes |
| Add multiple items at once | No | Yes |
| Player chest shops | Up to 25 per player, 30 on a linked server | Unlimited, set per player |
| Admin chest shops | Up to 25 | Unlimited |
| Chest shop staff, discounts and trade limits | No | Yes |
| Chest shops paid in items or in other currencies | Default currency only | Yes |
| Remote trading, map markers and `/chestshop market` | No | Yes |
| Purging inactive chest shops | No | Yes |
| Admin sign shops | Up to 20 | Unlimited |
| Purchase history | Yes | Yes |
| History filters and export | No | Yes |
| Undo | No | Yes |
| Search, preview and restock and sale alerts | No | Yes |
| Price modifiers (Sell Boosters add-on) | No | Yes |
| Price generator | Yes | Yes |
| Price audit | Loop count only | Yes |
| Discord webhooks | No | Yes |
| Auction House | Fixed-price listings, up to 10 per player, in the default currency, with the built-in categories | Adds auctions with bids, bundles, the watchlist, the price guide, listing again, more currencies, limits and tax by permission, tax and prices per currency and item, your own categories, the allow-list, `/ah open` and the server restock with automatic prices |
| Auction House migrations | Every listing, past the per-player limit | Yes |
| Migrations | Up to 3 shops, picked when there are more | Every shop |
| Chest shop migrations (QuickShop, Shop, ChestShop) | Every shop, past the per-player limit | Yes |
| Migrated stock and limit counts | No | Yes |
| Add-ons | None | Free add-ons, and the paid ones your license owns |

Premium buttons stay visible in the Lite editor, marked as Premium only. Clicking one closes the menu and sends a chat link to the Premium page. `/pshop history export`, and for `phoenixshop.admin` also `/pshop addons`, `/pshop audit`, `/pshop limits` and `/pshop stock`, answer on Lite with the same link.

When a shop, chest shop or sign shop limit stops a player holding `phoenixshop.admin`, the limit message is followed by the same link, and for the chest shop limit on a server that is not linked also by a pointer to `/pshop link`. Other players only see the limit message. Bedrock players cannot click chat links, so they also get the address as plain text, here and on the version notices below.

## How the Limits Behave

### Shops

Lite loads 3 shop files. Any other file in the shops folder is skipped with a console warning and left untouched, so it loads again the moment Premium is installed. The editor stops offering to create a shop once the limit is reached. When a migration would bring the server past 3 shops, it first lists the imported shops so you can pick as many as there are free slots, and they are added next to your current ones. When all 3 slots are taken, the migration asks you to delete a shop first and never replaces one.

### Chest and Sign Shops

On Lite every player can own up to 25 chest shops, or 30 on a [linked server](#linking-a-lite-server). [Max Per Player](../main-features/player-shops/settings.md#max-per-player) and the per-player permissions can lower that but not raise it. Admin chest shops work on Lite up to 25 across the server, and admin sign shops up to 20.

Staff, discounts, trade limits, paying with an item, currencies other than the default, remote trading, map markers, `/chestshop market` and purging inactive shops are Premium. On Lite their buttons show as Premium only to admins, players do not see them, and `/chestshop discount` and `/chestshop market` are not registered. Names, item displays, holograms, the shop list and find, teleporting, transfers, claims, tax and the rest of the settings work the same as on Premium. After a downgrade, staff keep their access, a running discount runs until it ends, trade limits stay in force, and shops in another currency or paid in items keep trading, but none of them can be set up or changed.

Chest shops brought in by a chest shop migration always load, even past 25, but count toward the limit, so a player at or over it cannot make another. After a downgrade, the other chest shops a player made past their first 30 are kept in the database but not loaded. Admin shops beyond the cap are kept the same way. Both load again once Premium is back.

### Currencies

Item and Placeholder currencies are not loaded on Lite, and the console says so once on startup. A shop priced in one of them does not open, and an item priced in one cannot be bought or sold.

### Database

If config.yml asks for MySQL or MariaDB on Lite, the plugin uses SQLite instead and warns in the console. Your database settings are left as they are.

### Add-ons

Lite loads no add-ons, custom ones included. Each jar in the addons folder is skipped with a console message, and an empty addons folder is removed on startup.

On Premium, a paid add-on loads only when it is attached to your license on phoenixplugins.com. Otherwise the console says it was not loaded, and the rest of the plugin runs as usual. Free and third-party add-ons always load. `/pshop addons` shows which ones are installed.

## Linking a Lite Server

Link a Lite server to your Phoenix Plugins account and every player can own 30 chest shops instead of 25. Run `/pshop link` with `phoenixshop.admin`. You get a link to click and a code to enter on the website; the code is valid for 15 minutes. Once you confirm it, the console and online admins are told the bonus is active. `/pshop link` on a linked server says so.

The link is remembered across restarts and website outages. Unlink a server on the website under **Settings > Linked Lite Servers**. After unlinking, players cannot make chest shops past 25, but the ones made while linked stay and keep loading.

## Server Statistics

Lite sends the server version, software, the domains players join through and the online player count to our servers on startup, every 5 minutes and on shutdown, so the server shows on the **My Servers** page of the website. `send-server-statistics` in config.yml turns it off. Linking works without it.

## Version Notices

Players holding `phoenixshop.admin` are told on join when a newer build is out, on Lite too, and the first time they join after an update they can click to see what changed. `/pshop changelog`, or the Changelog button in the editor, lists every released build with its changes. `notify-if-new-version` in config.yml turns the notices off.

## Upgrading to Premium

1. Stop the server.
2. Remove PhoenixShopLite-?.jar and add PhoenixShop-?.jar.
3. Copy the contents of `plugins/PhoenixShopLite` into `plugins/PhoenixShop`.
4. Start the server.

> **Warning:**
The two versions use different plugin folders. Skipping step 3 starts Premium with a fresh default shop instead of yours.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/licensing

---

# 🔒 Permissions

## Player Permissions

**Player Permissions**

| Permission | Default | Description |
| ---------- | ------- | ----------- |
| phoenixshop.command.buy | Everyone | Allows user to use `/pshop buy`. |
| phoenixshop.command.sell | Everyone | Allows user to use `/pshop sell`. |
| phoenixshop.sell.hand | OP | Allows user to use `/sell hand`. |
| phoenixshop.sell.handall | OP | Allows user to use `/sell handall`. |
| phoenixshop.sell.inventory | OP | Allows user to use `/sell inventory`. |
| phoenixshop.sell.menu | OP | Allows user to use `/sell menu`. |
| phoenixshop.sell.all | OP | Allows user to sell every matching item at once from a shop menu. |
| phoenixshop.buy.fill-inventory | OP | Allows user to fill the whole inventory in one purchase from the buy menu. |
| phoenixshop.sign.create | Everyone | Allows user to build a chest shop of their own. |
| phoenixshop.sign.limit.\<number> | Nobody | Sets how many chest shops the user can own, such as `phoenixshop.sign.limit.10`. With several, the highest counts. Without one, [Max Per Player](../main-features/player-shops/settings.md#max-per-player) applies. Lite caps it at 25. |
| phoenixshop.sign.limit.unlimited | OP | Removes the user's chest shop limit. Lite still caps it at 25. |
| phoenixshop.sign.transfer | Everyone | Allows user to hand their own chest shop to another player with `/chestshop transfer`. |
| phoenixshop.sign.list | Everyone | Allows user to use `/chestshop list`. |
| phoenixshop.sign.find | Everyone | Allows user to use `/chestshop find`. |
| phoenixshop.sign.teleport | Everyone | Allows user to teleport to a chest shop from `/chestshop list` and `/chestshop find`, while [Teleport](../main-features/player-shops/settings.md#teleport) is on. |
| phoenixshop.sign.remote | Everyone | Allows user to trade with a chest shop from `/chestshop list` and `/chestshop find` without walking to it, while [Remote Trading](../main-features/player-shops/settings.md#remote-trading) is on. |
| phoenixshop.search ⭐ | Everyone | Allows user to use `/pshop search`. |
| phoenixshop.undo ⭐ | Everyone | Allows user to use `/pshop undo`. |
| phoenixshop.alerts ⭐ | Everyone | Allows user to receive [restock and sale alerts](../features/restock-and-sale-alerts.md) and to use `/pshop alerts toggle`. |
| phoenixshop.preview ⭐ | Everyone | Allows user to preview what an item gives. |

> **Info:**
The `/sell` permissions default to OP. Give them to your players, or to a group, for `/sell` to work for them.

## Admin Permissions

**Admin Permissions**

| Permission | Description |
| ---------- | ----------- |
| phoenixshop.admin | Counts as every other permission on this page except the command ones, and allows `/pshop webhooktest`. |
| phoenixshop.command.editor | Allows user to use `/pshop editor` and `/pshop editlayout`. |
| phoenixshop.command.reload | Allows user to reload the plugin. |
| phoenixshop.command.changelog | Allows user to open the changelog with `/pshop changelog`. |
| phoenixshop.command.addons ⭐ | Allows user to list the add-ons with `/pshop addons`. |
| phoenixshop.command.open-others | Allows user to open a shop for another player. |
| phoenixshop.command.history | Allows user to open the purchase history, and to export it ⭐. |
| phoenixshop.command.prices | Allows user to open the price generator. |
| phoenixshop.command.audit ⭐ | Allows user to run the price audit. |
| phoenixshop.command.limits ⭐ | Allows user to reset a player's buy and sell limits with `/pshop limits`. |
| phoenixshop.command.stock ⭐ | Allows user to set and restock stock with `/pshop stock`. |
| phoenixshop.sign.bypass | Allows user to build a chest shop in one of the [Blocked Worlds](../main-features/player-shops/settings.md#blocked-worlds). Also skips the [claim check](../main-features/player-shops/settings.md#require-claim). |
| phoenixshop.sign.admin | Allows user to break anyone's chest shop, to make admin chest shops, and to place, break and edit admin sign shops. Also allows `/chestshop transfer` on any chest shop, `/chestshop transferall`, `/chestshop purge`, `/chestshop clean`, `/chestshop removeall`, `/chestshop removeworld`, `/chestshop ban` and `/chestshop unban`. |

Every admin permission defaults to OP.

> **Warning:**
phoenixshop.admin does not unlock the `/pshop` commands. Give each command its own permission, or grant `phoenixshop.command` to cover all of them.

## Shop Permissions

Each shop can require its own permission before a player can open it. It is empty by default, which leaves the shop open to everyone, and is set per shop from the editor. An admin opening a shop for another player skips that player's permission.

## Price Modifier Permissions ⭐

Each [price modifier](../add-ons/sell-boosters/README.md#price-modifiers) group of the Sell Boosters add-on names its own permission, such as `phoenixshop.modifier.vip`. It only counts when it is set on the player, directly or through a group, so OP alone does not give it.

## Sign Shop Permissions

**Sign Shop Permissions**

| Permission | Default | Description |
| ---------- | ------- | ----------- |
| phoenixshop.signs.use.\<shop> | OP | Allows user to use the admin sign shops of that shop that require a permission. |
| phoenixshop.signs.use.\* | OP | Allows user to use every admin sign shop that requires a permission. |
| phoenixshop.signs.buy-stack | Everyone | Allows user to buy a stack from a sign shop. |
| phoenixshop.signs.sell-stack | Everyone | Allows user to sell a stack to a sign shop. |
| phoenixshop.signs.buy-inventory | Everyone | Allows user to fill their inventory from a sign shop. |
| phoenixshop.signs.sell-all | Everyone | Allows user to sell everything that matches to a sign shop. |

A sign shop can name its own permission instead of `phoenixshop.signs.use.<shop>`.

## Add-on Permissions

The add-ons add permissions of their own, documented on each add-on's page.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/permissions

---

# 🔍 Placeholders

Phoenix Shop supports **PlaceholderAPI**, allowing you to use placeholders from other plugins inside the shop. Below is where PlaceholderAPI placeholders are read, as well as our **internal placeholders** that you can use in commands, menus and signs.

## PlaceholderAPI

The plugin registers the placeholders below. The AutoSell and Rotating Shop add-ons register their own, listed on their pages.

PlaceholderAPI placeholders are resolved for the player in:

* Purchase commands and sell commands.
* The input and output of a requirement. ⭐
* The balance of a Placeholder currency. ⭐

`<shop>`, `<category>` and `<item>` are identifiers, not display names, in any case. Separate them with `:`. An item is looked up in every category of the shop. A placeholder naming something that does not exist is left as it is.

### Sales ⭐

| Placeholder | Description |
| ----------- | ----------- |
| `%phoenixshop_sale_<shop>%` | The percent off of the shop-wide sale running now. `0` without one. |
| `%phoenixshop_sale_<shop>:<category>%` | The percent off the category gets now: its own sale, or the shop-wide one. |
| `%phoenixshop_sale_active_<shop>%`, `%phoenixshop_sale_active_<shop>:<category>%` | `true` while that sale runs, otherwise `false`. |
| `%phoenixshop_sale_ends_<shop>%`, `%phoenixshop_sale_ends_<shop>:<category>%` | The time until the running sale stops: its end date, the end of its time window or the end of its last day, whichever comes first. `-` when no sale runs, `Never` when it has no end. |
| `%phoenixshop_sale_ends_<shop>_seconds%`, `%phoenixshop_sale_ends_<shop>:<category>_seconds%` | The same in seconds. `0` when no sale runs, `-1` when it has no end. |

### Items

| Placeholder | Description |
| ----------- | ----------- |
| `%phoenixshop_buy_<shop>:<item>%` | The price the player pays for one purchase now, as the category menu shows it. `-` when the item cannot be bought. |
| `%phoenixshop_sell_<shop>:<item>%` | The price the player gets for one sale now. `-` when the item cannot be sold. |
| `%phoenixshop_buy_<shop>:<item>_raw%`, `%phoenixshop_sell_<shop>:<item>_raw%` | The same price as a plain number. `-1` when it cannot be bought or sold. |
| `%phoenixshop_stock_<shop>:<item>%` | The stock left, or `Unlimited`. ⭐ |
| `%phoenixshop_restock_<shop>:<item>%` | The time until the item restocks. `-` when no restock is due. ⭐ |
| `%phoenixshop_restock_<shop>:<item>_seconds%` | The same in seconds, `-1` when no restock is due. ⭐ |
| `%phoenixshop_limit_<shop>:<item>%` | How many more the player can buy before their purchase limit. `Unlimited` without a limit, `-` while the player is offline. ⭐ |

### Player Shops

| Placeholder | Description |
| ----------- | ----------- |
| `%phoenixshop_playershops%` | How many player shops the player owns. |
| `%phoenixshop_playershops_limit%` | How many they can own, or `Unlimited`. Limit permissions only count while the player is online. |
| `%phoenixshop_playershops_left%` | How many more they can create. |

### Player Stats ⭐

Counted from the purchase history: shops and admin sign shops, without player shop trades or undone transactions. They refresh about once a minute and show `0` until the first load.

| Placeholder | Description |
| ----------- | ----------- |
| `%phoenixshop_spent%`, `%phoenixshop_spent_<shop>%` | The money spent, per currency, separated by commas. |
| `%phoenixshop_earned%`, `%phoenixshop_earned_<shop>%` | The money earned, per currency. |
| `%phoenixshop_bought%`, `%phoenixshop_bought_<shop>%` | The number of items bought. |
| `%phoenixshop_sold%`, `%phoenixshop_sold_<shop>%` | The number of items sold. |
| `%phoenixshop_transactions%`, `%phoenixshop_transactions_<shop>%` | The number of transactions. |

### Leaderboards ⭐

The top 10 players, counted like the player stats. `<stat>` is `spent`, `earned`, `bought`, `sold` or `transactions`, and `<n>` is a place from 1 to 10. Add a shop before the place for that shop's board. A shop id may contain `_`, since the place is read from the end. Boards load the first time they are asked for, refresh every 5 minutes and stay empty until the first load.

Money boards rank one currency: `money` server-wide, the shop's own currency for a shop board. Trades in other currencies do not count there.

| Placeholder | Description |
| ----------- | ----------- |
| `%phoenixshop_top_<stat>_<n>_name%`, `%phoenixshop_top_<stat>_<shop>_<n>_name%` | The name of the player in that place. `-` when nobody holds it yet. |
| `%phoenixshop_top_<stat>_<n>_value%`, `%phoenixshop_top_<stat>_<shop>_<n>_value%` | Their total, in the ranked currency for `spent` and `earned`, a plain number otherwise. `-` when nobody holds the place. |
| `%phoenixshop_top_<stat>_position%`, `%phoenixshop_top_<stat>_<shop>_position%` | The player's own place on that board, `-` without any trade counted. |

For example `%phoenixshop_top_spent_1_name%` or `%phoenixshop_top_sold_ore_shop_3_value%`.

## Command Placeholders

Available in an item's purchase commands and sell commands.

| Placeholders | Description |
| ------------ | ----------- |
| %player% | The name of the player. |
| %amount% | The number of times the item was bought or sold. |
| %item% | The name of the item. |
| %price% | The total price paid or earned. |
| %currency% | The name of the currency. |
| %shop% | The name of the shop. |

## Placeholder Currency ⭐

Available in the buy and sell commands of a Placeholder currency, which always run from the console.

| Placeholders | Description |
| ------------ | ----------- |
| %player% | The name of the player. |
| %amount% | The amount to take or give. |
| %amount\_int% | The amount to take or give, rounded up to a whole number. |

## Menu Placeholders

Available in the titles, names and lore of the shop menus. Every `%shop%`, `%category%` and `%item%` has a `_colored` version that keeps the colors, such as `%shop_colored%`.

| Placeholders | Menus | Description |
| ------------ | ----- | ----------- |
| %shop% | Every menu | The name of the shop. |
| %category% | Category | The name of the category. |
| %player% | Category | The name of the player. |
| %item% | Buy, Sell, Bulk Buy, Bulk Sell | The name of the item. |
| %amount% | Buy, Sell | The number of items selected. |
| %lots% | Buy, Sell | The number of times the item is selected. |
| %max% | Buy, Sell | The most items the player can buy or sell. |
| %unit\_price% | Buy, Sell | The price of one. |
| %price% | Buy, Sell | The price of the selected amount. |
| %max\_price% | Buy, Sell | The price of the most the player can buy or sell. |
| %balance% | Buy, Sell | The balance of the player in the item's currency. |
| %stock% | Buy, Sell | The stock left of the item. ⭐ |
| %buy\_price\_base%, %sell\_price\_base% | Category, Search | The price before any [price modifier](../add-ons/sell-boosters/README.md#price-modifiers). ⭐ |
| %price\_base%, %unit\_price\_base% | Buy, Sell | The price before any price modifier. ⭐ |
| %price\_base% | Bulk Buy, Bulk Sell | The price before any price modifier. ⭐ |
| %sale% | Main, Category | The [category sale](../main-features/categories/edit-category.md#sale) badge while the sale runs, empty otherwise. ⭐ |
| %sale_ends% | Main | A line with the time left on the sale, counting down every second. Left out while no sale with an end is running. ⭐ |
| %category\_lore% | Main | The category's [lore](../main-features/categories/edit-category.md#lore), or its icon item's lore when none is set. One line of the template per lore line. |
| %count%, %price% | Preview | How many items one purchase gives, and its price. ⭐ |

## Message Placeholders

Available in the messages sent after a transaction.

| Placeholders | Description |
| ------------ | ----------- |
| %amount% | The number of items bought or sold. |
| %item% | The name of the item. |
| %price% | The total price paid or earned. |
| %currency% | The name of the currency. |
| %balance% | The balance of the player after the transaction. |

## Sign Shop Placeholders

Available in the lines of an admin sign shop.

| Placeholders | Description |
| ------------ | ----------- |
| %id% | The identifier of the sign. |
| %name% | The name of the sign. |
| %shop% | The name of the shop. |
| %category% | The name of the category. |
| %item% | The name of the item. |
| %amount% | The number of items per click. |
| %stock% | The stock left of the item. ⭐ |
| %buy\_price% | The buy price per click. |
| %sell\_price% | The sell price per click. |
| %mode% | Whether the sign buys, sells or both. |

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/placeholders

---

# ⁉️ Questions & Answers

## Setup and opening shops

<details id="why-does-my-shop-say-it-cannot-open">

<summary>Why does my shop say it cannot open?</summary>

A shop checks its own currency before it opens, and says what is wrong instead of opening a menu where nothing can be clicked.

| Message                                   | Cause                                                                                   |
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
| **cannot open: it is priced in ...**      | The plugin behind the shop's currency is not installed, such as Vault for money. Install it and run /pshop reload, or pick another currency for the shop. |
| **is priced in ..., which is not a currency this plugin knows** | The currency named in the shop file does not exist, often a typo or an ExcellentEconomy currency that was removed. |
| **is turned off**                         | The shop is disabled.                                                                   |
| **You don't have permission to do that**  | The shop has a permission and the player does not have it.                              |

On start, the console also lists every currency whose plugin is missing, with the plugin to install.

> **Info:**
The default shop is priced in money, which needs Vault and an economy plugin such as EssentialsX. See [Do I need Vault?](#do-i-need-vault)

</details>

<details id="do-i-need-vault">

<summary>Do I need Vault?</summary>

Only to use money. Phoenix Shop has no required dependencies, but the default shop is priced in money, which needs Vault and an economy plugin such as EssentialsX. Without them the shop does not open and says which plugin is missing. On Folia, use VaultUnlocked instead of Vault.

To run without Vault, change the shop's currency to one that needs no economy plugin.

| Currency          | Needs                                  |
| ----------------- | -------------------------------------- |
| Money             | Vault and an economy plugin            |
| Points            | PlayerPoints                           |
| Vote Points       | VotingPlugin                           |
| ExcellentEconomy  | ExcellentEconomy                       |
| PhoenixCurrencies | PhoenixCurrencies                      |
| Levels            | Nothing                                |
| Item ⭐           | Nothing                                |
| Placeholder ⭐    | PlaceholderAPI                         |

The creation cost of a chest shop is always charged in money, so it needs Vault too. PlaceholderAPI is also needed for requirements that compare placeholders ⭐.

</details>

<details id="why-doesnt-my-shop-command-work">

<summary>Why doesn't my shop's own command work?</summary>

Another plugin already owns that command. Phoenix Shop does not take a command away from another plugin, so the shop is left without a command of its own, and the console says so on start.

Pick a command nobody else uses in the shop's settings, or open the shop with /pshop open \<shop>, which always works.

A new or changed command is registered straight away from the editor, and on /pshop reload after editing the file.

</details>

<details id="why-is-cs-an-unknown-command">

<summary>Why is /cs an unknown command for my players?</summary>

WorldEdit and FastAsyncWorldEdit have a /cs command of their own and hide it from players without their permission. Phoenix Shop takes the label over and, on Paper, puts its own /cs back into the command list every player receives, so it works for everyone.

If /cs still shows in red, another plugin is removing it after Phoenix Shop. Players can always use /chestshop, or you can change the aliases in the chest-shop section of config.yml to one no other plugin uses, such as `cshop`, and run /pshop reload. See [Chest Shop Command](../../main-features/player-shops/settings.md#chest-shop-command).

</details>

<details id="why-cant-i-create-a-second-shop">

<summary>Why can't I create another shop?</summary>

The Lite version holds up to 3 shops. The **New Shop** button in the editor shows the count, such as `3/3`, and stops creating shops once it is reached. Categories are not limited, so one shop can hold as many categories as you like.

A shop file past the third dropped into the `shops` folder by hand is not loaded either. The console says so, and the file is left untouched.

```
Not loading shop "vip": the Lite edition holds 3 shops, Premium loads all of them. The file is still there and was not changed.
```

A migration that brings more shops than are free asks which ones to keep.

Unlimited shops are part of the [Premium version](https://www.phoenixplugins.com).

</details>

<details id="what-does-missing-translation-mean">

<summary>What does "Missing translation" mean?</summary>

The plugin tried to show a message that is in neither your translation file nor the one inside the jar. The console names it:

```
Missing translation for "..."
```

This almost always means an add-on and the plugin come from different versions. Update both to the latest build and restart.

A key you deleted from your translation file does not cause it. Missing keys are written back with their English default on the next start, and the console prints `Missing value for key "..."` for each one.

See [Languages & Translations](../../configurations/languages.md).

</details>

## Items and selling

<details id="why-is-an-item-missing-from-my-shop">

<summary>Why is an item missing from my shop?</summary>

A category only shows the items a player can actually trade. An item is hidden when:

* It is **disabled**.
* Its **currency cannot be used**, because the plugin behind it is not installed. The editor warns about this on the item's currency option. This is the most common cause when an item or a category overrides the shop's currency.
* Its **material does not exist** on your server version.

A whole category is hidden when it is disabled.

An item whose buy and sell prices are both `0` is still shown, but it can be neither bought nor sold.

</details>

<details id="why-is-my-item-shown-as-dirt">

<summary>Why is my item shown as dirt?</summary>

The item comes from another plugin, such as `itemsadder:ruby` or `nexo:silver`, and that plugin is not installed or does not know the item. The shop shows dirt in its place, and the item cannot be bought or sold until it loads.

The console names the item the first time it happens:

```
Shop item "ruby" uses "itemsadder:ruby", which could not be loaded. It shows as dirt and cannot be bought or sold.
```

Install the plugin, or fix the item's id, and run /pshop reload. The prefix of each supported plugin is listed on [Shop Configuration File](../../configurations/shop-configuration-file.md#materials).

</details>

<details id="why-wont-the-shop-accept-my-item-when-selling">

<summary>Why won't the shop accept my item when selling?</summary>

The item you hold has to match the shop item under that item's **Selling Rule**. The default is **Exact**, where the name, lore, enchantments and custom data must all be the same. A renamed, enchanted or damaged copy is refused.

When the shop item has [purchase items](../../main-features/items/README.md#purchase-items), selling matches against the first one, not against the item shown in the menu.

| Rule                  | What has to match                          |
| --------------------- | ------------------------------------------ |
| **Exact**             | Everything                                 |
| **Material And Name** | The material and the display name          |
| **Material**          | Only the material                          |

Loosen the rule only on items the shop does not sell, or a player can buy something cheap, change it and sell it back as something else.

If the rule is not the cause, check that:

* The item has a sell price. A price of `0` means it cannot be sold.
* The item and its category are enabled.
* The item's currency can be used, since an item whose currency plugin is missing cannot be sold.
* For /sell and the sell menu, the shop is listed under `sell.shops-whitelisted` in `config.yml` and the player can open it.

</details>

<details id="why-does-shift-right-click-say-i-need-a-permission">

<summary>Why does shift + right-click say I need a permission?</summary>

By default, shift + right-click on an item sells every matching item the player carries. That action needs `phoenixshop.sell.all`, which only operators have by default. Give it to your players with your permission plugin, or change what the click does under `click-mappings` in `config.yml`.

See [Main Configuration](../../configurations/main-configuration.md#click-mappings).

</details>

<details id="why-does-a-spawner-show-a-warning-in-its-tooltip">

<summary>Why does a spawner show a warning in its tooltip?</summary>

A spawner that spawns a set mob carries block data, and the game client adds a warning line to the tooltip of any item that does. It is not an error from the plugin, and the spawner works normally once placed.

The plugin cannot remove that warning without removing the mob from the item, which would break stacking plugins that read it. On Paper 1.21.5 and newer it does hide the extra line naming the mob, so name the spawner or add the mob to its lore if players should see which one it is.

</details>

## Compatibility and purchases

<details id="is-phoenixshop-folia-compatible">

<summary>Is PhoenixShop Folia compatible?</summary>

Yes, both the free and the premium version run on Folia.

</details>

<details id="does-the-plugin-support-bedrock-versions">

<summary>Does the plugin support Bedrock players?</summary>

Yes. With Geyser or Floodgate installed, Bedrock players get native forms instead of chest menus, with buttons, amount sliders and confirmations. A Bedrock player who prefers the chest menus can switch with /pshop forms.

Every option is on [GeyserMC / Bedrock](../../configurations/geysermc-bedrock.md).

</details>

<details id="can-the-plugin-run-as-a-forge-or-fabric-mod">

<summary>Can the plugin run as a Forge or Fabric mod?</summary>

No. It is a Java plugin and there is no mod version of it.

Hybrid servers such as Arclight or Mohist can load it, but we do not recommend them. Faults caused by the hybrid itself are not plugin issues.

</details>

<details id="do-you-offer-refunds">

<summary>Do you offer refunds?</summary>

No. Once the product has been downloaded it is not refundable.

See point 7 of our [Terms and Conditions](https://www.phoenixplugins.com/terms-and-conditions).

</details>

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers

---

# ⁉️ Can the plugin run as a Forge or Fabric mod?

## Answer

No. It is a Java plugin and there is no mod version of it.

Hybrid servers such as Arclight or Mohist can load it, but we do not recommend them. Faults caused by the hybrid itself are not plugin issues.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/can-the-plugin-run-as-a-forge-or-fabric-mod

---

# ⁉️ Does the plugin support bedrock versions?

## Answer

Yes. With Geyser or Floodgate installed, Bedrock players get native forms instead of chest menus, with buttons, amount sliders and confirmations. A Bedrock player who prefers the chest menus can switch with /pshop forms.

Every option is on [GeyserMC / Bedrock](../../configurations/geysermc-bedrock.md).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/does-the-plugin-support-bedrock-versions

---

# ❓ Do I need Vault?

## Answer

Only to use money. Phoenix Shop has no required dependencies, but the default shop is priced in money, which needs Vault and an economy plugin such as EssentialsX. Without them the shop does not open and says which plugin is missing. On Folia, use VaultUnlocked instead of Vault.

To run without Vault, change the shop's currency to one that needs no economy plugin.

| Currency          | Needs                                  |
| ----------------- | -------------------------------------- |
| Money             | Vault and an economy plugin            |
| Points            | PlayerPoints                           |
| Vote Points       | VotingPlugin                           |
| ExcellentEconomy  | ExcellentEconomy                       |
| PhoenixCurrencies | PhoenixCurrencies                      |
| Levels            | Nothing                                |
| Item ⭐           | Nothing                                |
| Placeholder ⭐    | PlaceholderAPI                         |

The creation cost of a chest shop is always charged in money, so it needs Vault too. PlaceholderAPI is also needed for requirements that compare placeholders ⭐.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/do-i-need-vault

---

# ⁉️ Do you offer refunds?

## Answer

No. Once the product has been downloaded it is not refundable.

See point 7 of our [Terms and Conditions](https://www.phoenixplugins.com/terms-and-conditions).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/do-you-offer-refunds

---

# ⁉️ Is PhoenixShop Folia compatible?

## Answer

Yes, both the free and the premium version run on Folia.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/is-phoenixshop-folia-compatible

---

# ❓ What does "Missing translation" mean?

## Answer

The plugin tried to show a message that is in neither your translation file nor the one inside the jar. The console names it:

```
Missing translation for "..."
```

This almost always means an add-on and the plugin come from different versions. Update both to the latest build and restart.

A key you deleted from your translation file does not cause it. Missing keys are written back with their English default on the next start, and the console prints `Missing value for key "..."` for each one.

See [Languages & Translations](../../configurations/languages.md).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/what-does-missing-translation-mean

---

# ❓ Why can't I create another shop?

## Answer

The Lite version holds up to 3 shops. The **New Shop** button in the editor shows the count, such as `3/3`, and stops creating shops once it is reached. Categories are not limited, so one shop can hold as many categories as you like.

A shop file past the third dropped into the `shops` folder by hand is not loaded either. The console says so, and the file is left untouched.

```
Not loading shop "vip": the Lite edition holds 3 shops, Premium loads all of them. The file is still there and was not changed.
```

A migration that brings more shops than are free asks which ones to keep.

Unlimited shops are part of the [Premium version](https://www.phoenixplugins.com).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-cant-i-create-a-second-shop

---

# ❓ Why does a spawner show a warning in its tooltip?

## Answer

A spawner that spawns a set mob carries block data, and the game client adds a warning line to the tooltip of any item that does. It is not an error from the plugin, and the spawner works normally once placed.

The plugin cannot remove that warning without removing the mob from the item, which would break stacking plugins that read it. On Paper 1.21.5 and newer it does hide the extra line naming the mob, so name the spawner or add the mob to its lore if players should see which one it is.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-does-a-spawner-show-a-warning-in-its-tooltip

---

# ❓ Why does my shop say it cannot open?

## Answer

A shop checks its own currency before it opens, and says what is wrong instead of opening a menu where nothing can be clicked.

| Message                                   | Cause                                                                                   |
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
| **cannot open: it is priced in ...**      | The plugin behind the shop's currency is not installed, such as Vault for money. Install it and run /pshop reload, or pick another currency for the shop. |
| **is priced in ..., which is not a currency this plugin knows** | The currency named in the shop file does not exist, often a typo or an ExcellentEconomy currency that was removed. |
| **is turned off**                         | The shop is disabled.                                                                   |
| **You don't have permission to do that**  | The shop has a permission and the player does not have it.                              |

On start, the console also lists every currency whose plugin is missing, with the plugin to install.

> **Info:**
The default shop is priced in money, which needs Vault and an economy plugin such as EssentialsX. See [Do I need Vault?](do-i-need-vault.md)

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-does-my-shop-say-it-cannot-open

---

# ❓ Why doesn't my shop's own command work?

## Answer

Another plugin already owns that command. Phoenix Shop does not take a command away from another plugin, so the shop is left without a command of its own, and the console says so on start.

Pick a command nobody else uses in the shop's settings, or open the shop with /pshop open \<shop>, which always works.

A new or changed command is registered straight away from the editor, and on /pshop reload after editing the file.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-doesnt-my-shop-command-work

---

# ❓ Why does shift + right-click say I need a permission?

## Answer

By default, shift + right-click on an item sells every matching item the player carries. That action needs `phoenixshop.sell.all`, which only operators have by default. Give it to your players with your permission plugin, or change what the click does under `click-mappings` in `config.yml`.

See [Main Configuration](../../configurations/main-configuration.md#click-mappings).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-does-shift-right-click-say-i-need-a-permission

---

# ❓ Why is an item missing from my shop?

## Answer

A category only shows the items a player can actually trade. An item is hidden when:

* It is **disabled**.
* Its **currency cannot be used**, because the plugin behind it is not installed. The editor warns about this on the item's currency option. This is the most common cause when an item or a category overrides the shop's currency.
* Its **material does not exist** on your server version.

A whole category is hidden when it is disabled.

An item whose buy and sell prices are both `0` is still shown, but it can be neither bought nor sold.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-is-an-item-missing-from-my-shop

---

# ❓ Why is my item shown as dirt?

## Answer

The item comes from another plugin, such as `itemsadder:ruby` or `nexo:silver`, and that plugin is not installed or does not know the item. The shop shows dirt in its place, and the item cannot be bought or sold until it loads.

The console names the item the first time it happens:

```
Shop item "ruby" uses "itemsadder:ruby", which could not be loaded. It shows as dirt and cannot be bought or sold.
```

Install the plugin, or fix the item's id, and run /pshop reload. The prefix of each supported plugin is listed on [Shop Configuration File](../../configurations/shop-configuration-file.md#materials).

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-is-my-item-shown-as-dirt

---

# ❓ Why won't the shop accept my item when selling?

## Answer

The item you hold has to match the shop item under that item's **Selling Rule**. The default is **Exact**, where the name, lore, enchantments and custom data must all be the same. A renamed, enchanted or damaged copy is refused.

When the shop item has [purchase items](../../main-features/items/purchase-items.md), selling matches against the first one, not against the item shown in the menu.

| Rule                  | What has to match                          |
| --------------------- | ------------------------------------------ |
| **Exact**             | Everything                                 |
| **Material And Name** | The material and the display name          |
| **Material**          | Only the material                          |

Loosen the rule only on items the shop does not sell, or a player can buy something cheap, change it and sell it back as something else.

If the rule is not the cause, check that:

* The item has a sell price. A price of `0` means it cannot be sold.
* The item and its category are enabled.
* The item's currency can be used, since an item whose currency plugin is missing cannot be sold.
* For /sell and the sell menu, the shop is listed under `sell.shops-whitelisted` in `config.yml` and the player can open it.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/questions-and-answers/why-wont-the-shop-accept-my-item-when-selling

---

# 📒 Version Support

## Version Support

The plugin supports Spigot, any Spigot forks, Paper and any Paper forks. It should also work on any custom modded servers.

> **Warning:**
Folia is supported, but the support is still **experimental**. Test it on a staging server before putting it in front of your players, and report anything you run into.

<table><thead><tr><th>Minecraft Version</th><th data-type="checkbox"></th></tr></thead><tbody><tr><td>26.x</td><td>true</td></tr><tr><td>1.21.x</td><td>true</td></tr><tr><td>1.20.4 - 1.20.6</td><td>true</td></tr><tr><td>1.20.3 and older</td><td>false</td></tr></tbody></table>

Bedrock players joining through GeyserMC get Bedrock forms instead of chest menus when Floodgate or Geyser is installed.

Source: https://www.phoenixplugins.com/docs/phoenix-shop/plugin-information/version-support

---

# 🏠 Homepage

## Introduction

Phoenix Shop is a GUI shop plugin built around an in-game editor. Shops, categories, items, prices and menus are all set up without touching a file, and every shop gets its own command. Players buy and sell through menus, the `/sell` command, chest shops they build themselves or sign shops placed by the staff.

Items can be priced in money, points, experience levels, another item or any PlaceholderAPI value, and shops from other plugins can be imported in a few clicks.

## Documentation

This doc page includes every feature provided by the plugin, both in the Lite and Premium versions. Be sure to take an in-depth look, and if you have any questions or suggestions, feel free to contact our team.

- Every feature exclusive to the Premium version is marked with a ⭐
- Every feature added via an add-on is marked with a 💎

## Premium Version

In the following table, you can see the additional perks available with the premium version of Phoenix Shop.

### Purchase Phoenix Shop from our [Website](https://www.phoenixplugins.com)

<table data-full-width="false"><thead><tr><th>Lite Version</th><th>Premium Extra Perks</th></tr></thead>
<tbody><tr><td>Shops Limit 3</td><td>Unlimited Shops</td></tr>
<tr><td>Currencies: Vault, PlayerPoints, VotingPlugin, ExcellentEconomy, PhoenixCurrencies, Levels</td><td>Item and Placeholder currencies</td></tr>
<tr><td>One currency per shop</td><td>Currency per category and per item</td></tr>
<tr><td>No Stock</td><td>Limited Stock, Player Limits and Restocking</td></tr>
<tr><td>No Requirements</td><td>Requirements with Deny Actions</td></tr>
<tr><td>No Category Actions</td><td>Open and Close Actions per Category</td></tr>
<tr><td>Menu Actions: Action Bar, Close Inventory, Sound, Title, Delay</td><td>Command, Gamemode, Message, Particle</td></tr>
<tr><td>Player Chest Shops, 25 per Player</td><td>Unlimited Player Chest Shops</td></tr>
<tr><td>Admin Chest Shops, 25 per Server</td><td>Unlimited Admin Chest Shops</td></tr>
<tr><td>Admin Sign Shops, 20 per Server</td><td>Unlimited Admin Sign Shops</td></tr>
<tr><td>Purchase History</td><td>History Filters and CSV Export</td></tr>
<tr><td>No Undo</td><td>Undo the Last Transaction</td></tr>
<tr><td>No Search</td><td>Search Across Every Shop</td></tr>
<tr><td>Price Generator</td><td>Price Audit</td></tr>
<tr><td>No Discord Webhooks</td><td>Discord Webhooks</td></tr>
<tr><td>Migrations Bring Up to 3 Picked Shops</td><td>Migrate Every Shop</td></tr>
<tr><td>SQLite Database Support</td><td>MySQL and MariaDB Database Support</td></tr>
<tr><td>No Add-ons</td><td>Free Add-ons and the Paid Ones Your License Owns</td></tr>
<tr><td>Community Based Support</td><td>Specialized Support</td></tr>
<tr><td>Response Time ( NO ETA )</td><td>Response Time ( 1-48 Hours )</td></tr>
<tr><td>Hot Fixes ( NO ETA )</td><td>Bug Fixes ( 1-7 Days )</td></tr>
<tr><td>Doesn't Include a Discord Role</td><td>Discord Role</td></tr></tbody></table>

The premium version includes all the features of the Lite version, along with additional premium features. The full breakdown is on [Licensing](plugin-information/licensing.md).

## Bug Reports

Before reporting an issue to our team, make sure you have tested the latest available build. If you are experiencing an issue on an older version, it will likely not be checked by our team.

Source: https://www.phoenixplugins.com/docs/phoenix-shop