📂 Shop Configuration File

#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

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. Lite reads only permission checks. Empty lets everyone in.
currency	What every item in the shop is priced in. See 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 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

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.
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.
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. 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.

'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.
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.
enabled	A disabled item is hidden from players.
purchase-items	What a purchase gives. The display item is never given. See Purchase Items.
purchase-commands	Commands run on a purchase. See Commands.
sell-commands	Commands run on a sale.
sell-item	What a sale takes from the player, with material, amount and the 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.
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.
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.
requirements ⭐	Checks a purchase or a sale has to pass. See 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.
EXPERIENCE	Experience points, or levels with levels: true.
ITEM ⭐	An item used as money.
PLACEHOLDER ⭐	Any number a PlaceholderAPI placeholder returns.

currency:
  type: EXCELLENTECONOMY
  identifier: gems

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

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.

#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.

#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.

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.

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.

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.

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.