מדריך עיון ל-API: חנות

{
  "items": [
    {
      "id": 98765,
      "main": true,
      "name": "Example",
      "emoji": "🪙",
      "description": "example",
      "color": "#18d7ff",
      "enabled": true,
      "channelIds": [
        "234567890123456789"
      ],
      "itemCount": 10
    }
  ]
}

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/stores" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/stores', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/stores",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "items": [
    {
      "id": 98765,
      "storeId": 98765,
      "name": "Example",
      "description": "example",
      "emoji": "🪙",
      "price": 250,
      "type": "role",
      "category": "example",
      "roleId": "234567890123456789",
      "durationSec": 10,
      "consumable": true,
      "fulfillment": true,
      "stock": 10,
      "perUserLimit": 10,
      "requiredRoleIds": [
        "234567890123456789"
      ],
      "minLevel": 10,
      "enabled": true,
      "hidden": true,
      "sortOrder": 10
    }
  ],
  "currency": {
    "name": "Example",
    "plural": "example",
    "emoji": "🪙"
  }
}

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "id": 98765,
  "storeId": 98765,
  "name": "Example",
  "description": "example",
  "emoji": "🪙",
  "price": 250,
  "type": "role",
  "category": "example",
  "roleId": "234567890123456789",
  "durationSec": 10,
  "consumable": true,
  "fulfillment": true,
  "stock": 10,
  "perUserLimit": 10,
  "requiredRoleIds": [
    "234567890123456789"
  ],
  "minLevel": 10,
  "enabled": true,
  "hidden": true,
  "sortOrder": 10
}

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items/234567890123456789', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items/234567890123456789",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "id": 98765,
  "storeId": 98765,
  "name": "Example",
  "description": "example",
  "emoji": "🪙",
  "price": 250,
  "type": "role",
  "category": "example",
  "roleId": "234567890123456789",
  "durationSec": 10,
  "consumable": true,
  "fulfillment": true,
  "stock": 10,
  "perUserLimit": 10,
  "requiredRoleIds": [
    "234567890123456789"
  ],
  "minLevel": 10,
  "enabled": true,
  "hidden": true,
  "sortOrder": 10
}

curl -s -X PATCH "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"stock":10}'

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items/234567890123456789', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true,
    stock: 10,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os
import requests

res = requests.patch(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items/234567890123456789",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    json={
        "enabled": True,
        "stock": 10,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "items": [
    {
      "id": 98765,
      "itemId": 98765,
      "storeId": 98765,
      "storeName": "example",
      "itemName": "example",
      "itemEmoji": "🪙",
      "itemType": "example",
      "userId": "876543210987654321",
      "price": 250,
      "status": "owned",
      "roleId": "234567890123456789",
      "expiresAt": "2026-10-07T12:00:00.000Z",
      "roleRemovedAt": "2026-10-07T12:00:00.000Z",
      "fulfillment": "none",
      "bankTransactionId": 98765,
      "refundTransactionId": 98765,
      "usedAt": "2026-10-07T12:00:00.000Z",
      "refundedAt": "2026-10-07T12:00:00.000Z",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "roleActive": true
    }
  ]
}

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/inventory" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/inventory', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/inventory",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "items": [
    {
      "id": 98765,
      "itemId": 98765,
      "storeId": 98765,
      "storeName": "example",
      "itemName": "example",
      "itemEmoji": "🪙",
      "itemType": "example",
      "userId": "876543210987654321",
      "price": 250,
      "status": "owned",
      "roleId": "234567890123456789",
      "expiresAt": "2026-10-07T12:00:00.000Z",
      "roleRemovedAt": "2026-10-07T12:00:00.000Z",
      "fulfillment": "none",
      "bankTransactionId": 98765,
      "refundTransactionId": 98765,
      "usedAt": "2026-10-07T12:00:00.000Z",
      "refundedAt": "2026-10-07T12:00:00.000Z",
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "nextCursor": "98700"
}

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases?limit=25" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases?limit=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "limit": 25,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "id": 98765,
  "itemId": 98765,
  "storeId": 98765,
  "storeName": "example",
  "itemName": "example",
  "itemEmoji": "🪙",
  "itemType": "example",
  "userId": "876543210987654321",
  "price": 250,
  "status": "owned",
  "roleId": "234567890123456789",
  "expiresAt": "2026-10-07T12:00:00.000Z",
  "roleRemovedAt": "2026-10-07T12:00:00.000Z",
  "fulfillment": "none",
  "bankTransactionId": 98765,
  "refundTransactionId": 98765,
  "usedAt": "2026-10-07T12:00:00.000Z",
  "refundedAt": "2026-10-07T12:00:00.000Z",
  "createdAt": "2026-10-07T12:00:00.000Z"
}

curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases/234567890123456789', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases/234567890123456789",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "purchase": {
    "id": 98765,
    "itemId": 98765,
    "storeId": 98765,
    "storeName": "example",
    "itemName": "example",
    "itemEmoji": "🪙",
    "itemType": "example",
    "userId": "876543210987654321",
    "price": 250,
    "status": "owned",
    "roleId": "234567890123456789",
    "expiresAt": "2026-10-07T12:00:00.000Z",
    "roleRemovedAt": "2026-10-07T12:00:00.000Z",
    "fulfillment": "none",
    "bankTransactionId": 98765,
    "refundTransactionId": 98765,
    "usedAt": "2026-10-07T12:00:00.000Z",
    "refundedAt": "2026-10-07T12:00:00.000Z",
    "createdAt": "2026-10-07T12:00:00.000Z"
  },
  "balance": 1350
}

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/purchases" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"itemId":98765,"expectedPrice":10}'

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/purchases', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    itemId: 98765,
    expectedPrice: 10,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/purchases",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "itemId": 98765,
        "expectedPrice": 10,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "purchase": {
    "id": 98765,
    "itemId": 98765,
    "storeId": 98765,
    "storeName": "example",
    "itemName": "example",
    "itemEmoji": "🪙",
    "itemType": "example",
    "userId": "876543210987654321",
    "price": 250,
    "status": "owned",
    "roleId": "234567890123456789",
    "expiresAt": "2026-10-07T12:00:00.000Z",
    "roleRemovedAt": "2026-10-07T12:00:00.000Z",
    "fulfillment": "none",
    "bankTransactionId": 98765,
    "refundTransactionId": 98765,
    "usedAt": "2026-10-07T12:00:00.000Z",
    "refundedAt": "2026-10-07T12:00:00.000Z",
    "createdAt": "2026-10-07T12:00:00.000Z"
  },
  "balance": 1350
}

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/grants" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"itemId":98765,"reason":"Tournament prize"}'

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/grants', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    itemId: 98765,
    reason: 'Tournament prize',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/grants",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "itemId": 98765,
        "reason": "Tournament prize",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

{
  "purchase": {
    "id": 98765,
    "itemId": 98765,
    "storeId": 98765,
    "storeName": "example",
    "itemName": "example",
    "itemEmoji": "🪙",
    "itemType": "example",
    "userId": "876543210987654321",
    "price": 250,
    "status": "owned",
    "roleId": "234567890123456789",
    "expiresAt": "2026-10-07T12:00:00.000Z",
    "roleRemovedAt": "2026-10-07T12:00:00.000Z",
    "fulfillment": "none",
    "bankTransactionId": 98765,
    "refundTransactionId": 98765,
    "usedAt": "2026-10-07T12:00:00.000Z",
    "refundedAt": "2026-10-07T12:00:00.000Z",
    "createdAt": "2026-10-07T12:00:00.000Z"
  },
  "balance": 1350
}

curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases/234567890123456789/refund" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"restock":true,"force":true,"reason":"Tournament prize"}'

// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases/234567890123456789/refund', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    restock: true,
    force: true,
    reason: 'Tournament prize',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);

import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases/234567890123456789/refund",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "restock": True,
        "force": True,
        "reason": "Tournament prize",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)