Minecraft plugin

Install and configure the plugin that automatically delivers purchases on your server.

The plugin connects your game server to the shop and runs the commands of paid orders — without your involvement. It connects on its own over an encrypted outbound connection, so you don’t open any ports. If the server was offline, pending deliveries are caught up after it reconnects.

Requirements

• Java 17 or newer,
• Paper/Spigot 1.19+, Folia, BungeeCord or Velocity 3.x,
• a server added in the panel (see Servers),
• write access to the plugins/ItemShop/ folder (configuration and fulfillment journal).

Install the plugin

1. Download the plugin

   In the Plugin section of the panel, download the universal JAR and put it in the plugins/ folder. Don’t install several plugin variants at the same time.

2. Generate the key and configuration

   Choose the server and click Generate plugin key, then copy or download the ready config.yml. The key is shown only once — if you lose it, generate a new one.

3. Upload the configuration

   Save the file as plugins/ItemShop/config.yml and start the server.

4. Check the connection

   The /itemshop command shows the connection status. In the panel, the server should switch to online.

Generate the key before copying the file. A file without a key contains WKLEJ_TUTAJ_KLUCZ instead of the key and won’t work.

One configuration covers one server. If you have several servers, generate a separate config.yml for each. After changing servers in the panel, generate the file again.

Configuration

The generator fills everything in for you. Example file:

config.yml

apiUrl: "https://itemshop.dev"
apiKey: "isk_..."
serverId: "..."
joinDeliveryDelaySeconds: 2
blockedCommands:
  - op
  - deop
  - stop
  - restart
  - reload
  - whitelist
blockedServers:
  - auth
  - login
playersUpdateIntervalSeconds: 30
sendPlayerNames: true
debug: false

Field	Meaning
apiUrl	ItemShop address — without /api/v2 and without a path; always https:// in production
apiKey	plugin key (starts with isk_)
serverId	ID of one server from the panel
joinDeliveryDelaySeconds	delay before delivery after a player joins
blockedCommands	commands the plugin never runs, even if a product contains them
blockedServers	proxy modes where delivery waits (e.g. a login lobby)
playersUpdateIntervalSeconds	how often the plugin sends the online player count
sendPlayerNames	whether to also send the list of nicknames (the player count is always sent)
debug	verbose logs — turn on only while troubleshooting

Load changes with /itemshop reload. Don’t use the server-wide /reload — it can leave the plugin in an inconsistent state.

Security

• The plugin key only works for fulfilling your shop’s orders, but treat it like a password: don’t publish config.yml, commit it to a repository or paste it into support tickets.
• If the key may have leaked, generate a new one and delete the old one under API keys (see API keys).
• Don’t delete the fulfillment-journal.json file in the plugin folder — without it, a delivery interrupted by a crash can’t be resolved safely.

How delivery works

A paid order reaches the plugin immediately. If several instances are connected, only one runs the commands. Before the first command the plugin saves its state to disk, so after a crash it knows where it stopped:

• if all commands ran, after a restart the plugin only confirms the fulfillment — it doesn’t repeat the commands,
• if the server crashed while running commands, the outcome is uncertain. The order then goes to manual verification and you decide: complete or retry (see Orders).

This is deliberate: it’s better to ask you than to risk giving the product twice. Technical details are in the plugin protocol.

Test before selling

1. Create a product with a harmless test command, e.g. say Test {PLAYER}.
2. Buy it with a 100% discount code — no payment provider involved.
3. Check /itemshop, the server log and the status change: Paid → Processing → Completed.
4. Repeat with the player offline, after the player joins, and after restarting the server before delivery.
5. Separately, test the real provider in test mode (see Payments).

Troubleshooting

The plugin reports missing configuration

Check the exact field names: apiUrl, apiKey, serverId. The key must start with isk_, and apiUrl must not end with /api/v2.

The connection is rejected (unauthorized)

Generate a new key in the Plugin section. The key must be active and belong to the same shop as the serverId.

An order is waiting for the player

Check the nickname spelling, the Require player online toggle and the blockedServers list. A player joining or switching modes triggers delivery of pending orders after joinDeliveryDelaySeconds.

An order needs manual verification

The plugin detected an interrupted delivery — some commands may have run. First check the player’s state and the server logs, then choose complete or retry in the panel.

The server shows as offline in the panel

The plugin hasn’t sent a heartbeat for more than 5 minutes. Check /itemshop, the server log and whether the server has internet access. Orders will wait until it reconnects.

Next

Servers

Server features and online status.

Plugin protocol

Technical description of how the plugin talks to the shop.