Quickstart

From a shop key to your first safe REST API calls.

This guide creates a server and product with a key bound to one shop. Every path is prefixed with /api/v2.

1. Prepare the shop and key

1. Sign in to the dashboard and create a shop.
2. Save its 24-character shopId.
3. Under API Keys, create a Store (integration) key.
4. Grant servers:write and products:write. Save the secret; it is shown once.

Do not use a Plugin key for general REST calls. It is confined to the real-time fulfillment protocol.

2. Add a server

curl -X POST https://api.itemshop.dev/api/v2/servers/<shopId> \
  -H "X-API-Key: <shop-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Survival", "domain": "play.my-shop.com" }'

Save data._id as serverId.

3. Add a product

curl -X POST https://api.itemshop.dev/api/v2/products/<shopId> \
  -H "X-API-Key: <shop-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Rank",
    "serverId": "<serverId>",
    "price": 19.99,
    "commands": ["lp user {PLAYER} parent set vip"]
  }'

products:write includes read access, so verify the result immediately:

curl https://api.itemshop.dev/api/v2/products/<shopId>?active=true \
  -H "X-API-Key: <shop-key>"

4. Complete the safe sales flow

• configure a real provider and run its sandbox test;
• install the plugin and generated config.yml with a dedicated plugin key;
• add the seller’s current legal documents;
• place an order through the storefront so checkout sends the real shown-document version, consents, Turnstile token, and Idempotency-Key;
• verify the full path: checkout → signed provider webhook → plugin claim → ACK.

Do not blindly copy a checkout request: public POST /orders deliberately requires data and consents originating from the current storefront.

Next steps

Authentication

Key types, scope, and error responses.

Payment methods

Provider setup and the required sandbox test.

Minecraft plugin

Installation, journal, and fulfillment diagnostics.

Error handling

Error envelope, statuses, and retries.