REST API v1 · 開發者 · API 參考

商店 API 參考

BotGG REST API v1 的所有 10 個 商店 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。

開發者文件
本頁目錄

端點

路徑皆相對於 https://console.botgg.app/api/v1。請以 Authorization: Bearer botgg_… 傳送你的 API 金鑰,ID 皆為字串。

商店 端點
端點範圍說明
GET/guilds/{guildId}/shop/storesshop:readList stores
GET/guilds/{guildId}/shop/itemsshop:readList items
GET/guilds/{guildId}/shop/items/{itemId}shop:readGet an item
PATCH/guilds/{guildId}/shop/items/{itemId}shop:writeRestock or turn an item on/off
GET/guilds/{guildId}/shop/members/{userId}/inventoryshop:readA member’s inventory
GET/guilds/{guildId}/shop/purchasesshop:readList purchases
GET/guilds/{guildId}/shop/purchases/{purchaseId}shop:readGet a purchase
POST/guilds/{guildId}/shop/members/{userId}/purchasesshop:writeBuy an item for a member
POST/guilds/{guildId}/shop/members/{userId}/grantsshop:writeGive an item to a member for free
POST/guilds/{guildId}/shop/purchases/{purchaseId}/refundshop:writeRefund a purchase

除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:

List stores

GET/guilds/{guildId}/shop/stores

範圍: shop:read

The built-in Main store (id: null, items without a store) first, then the stores in their order.

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idinteger | null是null = the built-in Main store
items[].mainboolean是
items[].namestring | null是null for the Main store
items[].emojistring | null是
items[].descriptionstring | null是
items[].colorstring | null是
items[].enabledboolean是
items[].channelIdsarray of string是
items[].itemCountinteger是
回應 · 200
{
  "items": [
    {
      "id": 98765,
      "main": true,
      "name": "Example",
      "emoji": "🪙",
      "description": "example",
      "color": "#18d7ff",
      "enabled": true,
      "channelIds": [
        "234567890123456789"
      ],
      "itemCount": 10
    }
  ]
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/stores" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

List items

GET/guilds/{guildId}/shop/items

範圍: shop:read

In sort order. Only enabled items unless includeDisabled=true; hidden items are included (hidden: true).

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
storeId查詢字串"main"否
category查詢字串string否1–32 個字元
includeDisabled查詢字串string否其中之一 1, 0, true, false

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idinteger是
items[].storeIdinteger | null是null = Main store
items[].namestring是
items[].descriptionstring | null是
items[].emojistring | null是
items[].priceinteger是
items[].typestring是其中之一 role, color, item
items[].categorystring | null是
items[].roleIdstring | null是
items[].durationSecinteger是Timed role length; 0 = permanent
items[].consumableboolean是
items[].fulfillmentboolean是Staff deliver it (fulfilment request)
items[].stockinteger | null是null = unlimited
items[].perUserLimitinteger | null是
items[].requiredRoleIdsarray of string是
items[].minLevelinteger是
items[].enabledboolean是
items[].hiddenboolean是
items[].sortOrderinteger是
currencyobject是
currency.namestring是
currency.pluralstring是
currency.emojistring | null是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Get an item

GET/guilds/{guildId}/shop/items/{itemId}

範圍: shop:read

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
itemId路徑string是

回應

回應欄位 · 200
欄位類型必填說明
idinteger是
storeIdinteger | null是null = Main store
namestring是
descriptionstring | null是
emojistring | null是
priceinteger是
typestring是其中之一 role, color, item
categorystring | null是
roleIdstring | null是
durationSecinteger是Timed role length; 0 = permanent
consumableboolean是
fulfillmentboolean是Staff deliver it (fulfilment request)
stockinteger | null是null = unlimited
perUserLimitinteger | null是
requiredRoleIdsarray of string是
minLevelinteger是
enabledboolean是
hiddenboolean是
sortOrderinteger是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/items/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Restock or turn an item on/off

PATCH/guilds/{guildId}/shop/items/{itemId}

範圍: shop:write敏感

Like /shopadmin restock and toggle. Send stock (null = unlimited) and/or enabled.

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
itemId路徑string是

請求內容

請求內容
欄位類型必填說明
enabledboolean否Off = not listed, not buyable
stockinteger | null否New stock; null = unlimited
0–1,000,000

回應

回應欄位 · 200
欄位類型必填說明
idinteger是
storeIdinteger | null是null = Main store
namestring是
descriptionstring | null是
emojistring | null是
priceinteger是
typestring是其中之一 role, color, item
categorystring | null是
roleIdstring | null是
durationSecinteger是Timed role length; 0 = permanent
consumableboolean是
fulfillmentboolean是Staff deliver it (fulfilment request)
stockinteger | null是null = unlimited
perUserLimitinteger | null是
requiredRoleIdsarray of string是
minLevelinteger是
enabledboolean是
hiddenboolean是
sortOrderinteger是
回應 · 200
{
  "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
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}'
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

A member’s inventory

GET/guilds/{guildId}/shop/members/{userId}/inventory

範圍: shop:read

Non-refunded purchases (owned and used), newest first; roleActive = a granted role that hasn’t expired or been removed.

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
userId路徑string是成員的 Discord 使用者 ID · Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idinteger是
items[].itemIdinteger | null是null when the item was deleted (the snapshot stays)
items[].storeIdinteger | null是
items[].storeNamestring | null是
items[].itemNamestring是
items[].itemEmojistring | null是
items[].itemTypestring是
items[].userIdstring是
items[].priceinteger是0 for free grants
items[].statusstring是其中之一 owned, used, refunded
items[].roleIdstring | null是
items[].expiresAtstring | null是
items[].roleRemovedAtstring | null是
items[].fulfillmentstring是其中之一 none, pending, done
items[].bankTransactionIdinteger | null是
items[].refundTransactionIdinteger | null是
items[].usedAtstring | null是
items[].refundedAtstring | null是
items[].createdAtstring是
items[].roleActiveboolean是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/members/876543210987654321/inventory" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

List purchases

GET/guilds/{guildId}/shop/purchases

範圍: shop:read

The purchase ledger, newest first. Pass before=<nextCursor> for the next page.

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
limit查詢字串integer否1–100 · 預設值 25
before查詢字串integer否至少 1
userId查詢字串string否Discord ID(字串)
itemId查詢字串integer否至少 1
storeId查詢字串"main"否
status查詢字串string否其中之一 owned, used, refunded

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idinteger是
items[].itemIdinteger | null是null when the item was deleted (the snapshot stays)
items[].storeIdinteger | null是
items[].storeNamestring | null是
items[].itemNamestring是
items[].itemEmojistring | null是
items[].itemTypestring是
items[].userIdstring是
items[].priceinteger是0 for free grants
items[].statusstring是其中之一 owned, used, refunded
items[].roleIdstring | null是
items[].expiresAtstring | null是
items[].roleRemovedAtstring | null是
items[].fulfillmentstring是其中之一 none, pending, done
items[].bankTransactionIdinteger | null是
items[].refundTransactionIdinteger | null是
items[].usedAtstring | null是
items[].refundedAtstring | null是
items[].createdAtstring是
nextCursorstring | null是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases?limit=25" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Get a purchase

GET/guilds/{guildId}/shop/purchases/{purchaseId}

範圍: shop:read

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
purchaseId路徑string是

回應

回應欄位 · 200
欄位類型必填說明
idinteger是
itemIdinteger | null是null when the item was deleted (the snapshot stays)
storeIdinteger | null是
storeNamestring | null是
itemNamestring是
itemEmojistring | null是
itemTypestring是
userIdstring是
priceinteger是0 for free grants
statusstring是其中之一 owned, used, refunded
roleIdstring | null是
expiresAtstring | null是
roleRemovedAtstring | null是
fulfillmentstring是其中之一 none, pending, done
bankTransactionIdinteger | null是
refundTransactionIdinteger | null是
usedAtstring | null是
refundedAtstring | null是
createdAtstring是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/shop/purchases/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Buy an item for a member

POST/guilds/{guildId}/shop/members/{userId}/purchases

範圍: shop:write敏感Idempotency-Key

Same rules as /shop: the price is charged from the member’s Bank balance in one transaction with the stock and limits; requirements (roles, level) apply. A role item’s role is given right away (if Discord refuses, nothing is charged). Fulfilment requests and the Shop log are posted like a /shop purchase.

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
userId路徑string是成員的 Discord 使用者 ID · Discord ID(字串)
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
itemIdinteger是至少 1
expectedPriceinteger否Refused with SHOP_ITEM_UNAVAILABLE (price_changed) when the price differs
0–1,000,000,000

回應

回應欄位 · 201
欄位類型必填說明
purchaseobject是
purchase.idinteger是
purchase.itemIdinteger | null是null when the item was deleted (the snapshot stays)
purchase.storeIdinteger | null是
purchase.storeNamestring | null是
purchase.itemNamestring是
purchase.itemEmojistring | null是
purchase.itemTypestring是
purchase.userIdstring是
purchase.priceinteger是0 for free grants
purchase.statusstring是其中之一 owned, used, refunded
purchase.roleIdstring | null是
purchase.expiresAtstring | null是
purchase.roleRemovedAtstring | null是
purchase.fulfillmentstring是其中之一 none, pending, done
purchase.bankTransactionIdinteger | null是
purchase.refundTransactionIdinteger | null是
purchase.usedAtstring | null是
purchase.refundedAtstring | null是
purchase.createdAtstring是
balanceinteger | null是The member’s balance afterwards (null when unchanged)
回應 · 201
{
  "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
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}'
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Give an item to a member for free

POST/guilds/{guildId}/shop/members/{userId}/grants

範圍: shop:write敏感Idempotency-Key

A staff grant: recorded as a purchase with price 0, no Bank change. Ignores the item’s on/off switch, a closed store, requirements and the per-member limit; stock still applies. A role item’s role is given right away.

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
userId路徑string是成員的 Discord 使用者 ID · Discord ID(字串)
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
itemIdinteger是至少 1
reasonstring | null否Shown in the audit log
最多 200 個字元

回應

回應欄位 · 201
欄位類型必填說明
purchaseobject是
purchase.idinteger是
purchase.itemIdinteger | null是null when the item was deleted (the snapshot stays)
purchase.storeIdinteger | null是
purchase.storeNamestring | null是
purchase.itemNamestring是
purchase.itemEmojistring | null是
purchase.itemTypestring是
purchase.userIdstring是
purchase.priceinteger是0 for free grants
purchase.statusstring是其中之一 owned, used, refunded
purchase.roleIdstring | null是
purchase.expiresAtstring | null是
purchase.roleRemovedAtstring | null是
purchase.fulfillmentstring是其中之一 none, pending, done
purchase.bankTransactionIdinteger | null是
purchase.refundTransactionIdinteger | null是
purchase.usedAtstring | null是
purchase.refundedAtstring | null是
purchase.createdAtstring是
balanceinteger | null是The member’s balance afterwards (null when unchanged)
回應 · 201
{
  "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
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"}'
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Refund a purchase

POST/guilds/{guildId}/shop/purchases/{purchaseId}/refund

範圍: shop:write敏感Idempotency-Key

Like Refund in the console: the price goes back to the member’s balance (one transaction), the purchase becomes refunded, optionally restocked; a granted role is removed by the bot within ~30 s.

需要在伺服器上啟用此功能: 商店

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
purchaseId路徑string是
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
restockboolean否Put the unit back in stock (default: the Shop’s “restock on refund” setting)
forceboolean否Also refund an item that was already used
reasonstring | null否Shown in the audit log
最多 200 個字元

回應

回應欄位 · 200
欄位類型必填說明
purchaseobject是
purchase.idinteger是
purchase.itemIdinteger | null是null when the item was deleted (the snapshot stays)
purchase.storeIdinteger | null是
purchase.storeNamestring | null是
purchase.itemNamestring是
purchase.itemEmojistring | null是
purchase.itemTypestring是
purchase.userIdstring是
purchase.priceinteger是0 for free grants
purchase.statusstring是其中之一 owned, used, refunded
purchase.roleIdstring | null是
purchase.expiresAtstring | null是
purchase.roleRemovedAtstring | null是
purchase.fulfillmentstring是其中之一 none, pending, done
purchase.bankTransactionIdinteger | null是
purchase.refundTransactionIdinteger | null是
purchase.usedAtstring | null是
purchase.refundedAtstring | null是
purchase.createdAtstring是
balanceinteger | null是The member’s balance afterwards (null when unchanged)
回應 · 200
{
  "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
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"}'
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。