> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://andcze.mintlify.site/en/shop/servers.md)),
* 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**.

> [!WARNING]
>
> 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:

```yaml config.yml theme={null}
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](https://andcze.mintlify.site/en/developers/api-keys.md)).
* 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](https://andcze.mintlify.site/en/shop/orders.md)).

This is deliberate: it's better to ask you than to risk giving the product twice. Technical details are in the [plugin protocol](https://andcze.mintlify.site/en/developers/plugin-protocol.md).

## 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](https://andcze.mintlify.site/en/shop/payments.md)).

## 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](https://andcze.mintlify.site/en/shop/servers.md)**
>
> Server features and online status.

> **[Plugin protocol](https://andcze.mintlify.site/en/developers/plugin-protocol.md)**
>
> Technical description of how the plugin talks to the shop.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.