Shop API

Browse available items, make purchases, and view weekly deals.

List Shop Items

Get all available shop items.

Endpoint: GET /api/shop/items

Authentication: Required (JWT)

Query Parameters:

• category - Filter by category (optional)
• page - Page number (default: 1)
• limit - Items per page (default: 20, max: 100)

Success Response (200):

{
  "success": true,
  "items": [
    {
      "id": "diamond_sword",
      "material": "DIAMOND_SWORD",
      "displayName": "Diamond Sword",
      "description": "A powerful weapon",
      "price": 500.0,
      "stock": 10,
      "category": "WEAPONS",
      "enchantments": [
        {
          "type": "SHARPNESS",
          "level": 3
        }
      ],
      "available": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Example:

curl "http://localhost:8080/api/shop/items?category=WEAPONS" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Purchase Item

Purchase an item from the shop.

Endpoint: POST /api/shop/purchase

Authentication: Required (JWT)

Request Body:

{
  "itemId": "diamond_sword",
  "quantity": 1
}

Success Response (200):

{
  "success": true,
  "message": "Purchase successful",
  "item": "Diamond Sword",
  "quantity": 1,
  "totalCost": 500.0,
  "newBalance": 4500.0,
  "deliveryMethod": "INVENTORY"
}

Example:

curl -X POST http://localhost:8080/api/shop/purchase \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "itemId": "diamond_sword",
    "quantity": 1
  }'

Error Responses:

• 400 - Invalid item ID or quantity
• 402 - Insufficient funds
• 404 - Item not found or out of stock
• 409 - Inventory full

---

Get Weekly Shop

View special weekly deals and limited-time offers.

Endpoint: GET /api/shop/weekly

Authentication: Required (JWT)

Success Response (200):

{
  "success": true,
  "weeklyDeals": [
    {
      "id": "weekly_diamond_pickaxe",
      "material": "DIAMOND_PICKAXE",
      "displayName": "Diamond Pickaxe",
      "originalPrice": 300.0,
      "salePrice": 225.0,
      "discount": 25,
      "stock": 5,
      "expiresAt": "2024-01-22T00:00:00Z"
    }
  ],
  "refreshesIn": "5 days",
  "nextRefresh": "2024-01-22T00:00:00Z"
}

Example:

curl http://localhost:8080/api/shop/weekly \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Get Shop Resources

Retrieve shop resource configurations (admin).

Endpoint: GET /api/shop/resources

Authentication: Required (JWT, Admin)

Success Response (200):

{
  "success": true,
  "resources": [
    {
      "id": "diamond",
      "material": "DIAMOND",
      "basePrice": 100.0,
      "stock": 500,
      "restock": {
        "enabled": true,
        "interval": "24h",
        "amount": 100
      }
    }
  ]
}

Example:

curl http://localhost:8080/api/shop/resources \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Get Available Resources

List all available resource types for shop configuration.

Endpoint: GET /api/shop/resources/available

Authentication: Required (JWT, Admin)

Success Response (200):

{
  "success": true,
  "resources": [
    "DIAMOND",
    "IRON_INGOT",
    "GOLD_INGOT",
    "EMERALD"
  ]
}

Example:

curl http://localhost:8080/api/shop/resources/available \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

Code Examples

TypeScript

interface ShopItem {
  id: string;
  material: string;
  displayName: string;
  price: number;
  stock: number;
  category: string;
}

class ShopAPI {
  constructor(private baseUrl: string, private token: string) {}
  
  async getItems(category?: string, page = 1, limit = 20) {
    const params = new URLSearchParams({
      page: page.toString(),
      limit: limit.toString()
    });
    if (category) params.append('category', category);
    
    const response = await fetch(
      `${this.baseUrl}/api/shop/items?${params}`,
      {
        headers: { 'Authorization': `Bearer ${this.token}` }
      }
    );
    return await response.json();
  }
  
  async purchaseItem(itemId: string, quantity: number) {
    const response = await fetch(`${this.baseUrl}/api/shop/purchase`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ itemId, quantity })
    });
    return await response.json();
  }
  
  async getWeeklyDeals() {
    const response = await fetch(`${this.baseUrl}/api/shop/weekly`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return await response.json();
  }
}

Python

class ShopAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def get_items(self, category=None, page=1, limit=20):
        params = {'page': page, 'limit': limit}
        if category:
            params['category'] = category
        
        response = requests.get(
            f'{self.base_url}/api/shop/items',
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def purchase_item(self, item_id, quantity):
        response = requests.post(
            f'{self.base_url}/api/shop/purchase',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json={'itemId': item_id, 'quantity': quantity}
        )
        return response.json()
    
    def get_weekly_deals(self):
        response = requests.get(
            f'{self.base_url}/api/shop/weekly',
            headers=self.headers
        )
        return response.json()

Categories

Available shop categories:

• WEAPONS - Swords, axes, bows
• TOOLS - Pickaxes, shovels, hoes
• ARMOR - Helmets, chestplates, leggings, boots
• BLOCKS - Building blocks
• MATERIALS - Raw materials
• FOOD - Consumables
• POTIONS - Potions and effects
• MISC - Other items

Notes

• Purchases deducted from player balance immediately
• Items delivered to player inventory or mailbox if full
• Weekly shop refreshes every Monday at midnight (server time)
• Stock levels shared across all players
• Prices may vary based on server economy settings

Related

• Economy API - Balance and transactions
• Players API - View inventory
• Admin API - Manage shop items