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/stores | shop:read | List stores |
GET/guilds/{guildId}/shop/items | shop:read | List items |
GET/guilds/{guildId}/shop/items/{itemId} | shop:read | Get an item |
PATCH/guilds/{guildId}/shop/items/{itemId} | shop:write | Restock or turn an item on/off |
GET/guilds/{guildId}/shop/members/{userId}/inventory | shop:read | A member’s inventory |
GET/guilds/{guildId}/shop/purchases | shop:read | List purchases |
GET/guilds/{guildId}/shop/purchases/{purchaseId} | shop:read | Get a purchase |
POST/guilds/{guildId}/shop/members/{userId}/purchases | shop:write | Buy an item for a member |
POST/guilds/{guildId}/shop/members/{userId}/grants | shop:write | Give an item to a member for free |
POST/guilds/{guildId}/shop/purchases/{purchaseId}/refund | shop:write | Refund a purchase |
除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:
List stores
GET/guilds/{guildId}/shop/stores
The built-in Main store (id: null, items without a store) first, then the stores in their order.
需要在伺服器上啟用此功能: 商店
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | integer | null | 是 | null = the built-in Main store |
items[].main | boolean | 是 | |
items[].name | string | null | 是 | null for the Main store |
items[].emoji | string | null | 是 | |
items[].description | string | null | 是 | |
items[].color | string | null | 是 | |
items[].enabled | boolean | 是 | |
items[].channelIds | array of string | 是 | |
items[].itemCount | integer | 是 |
{
"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)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
List items
GET/guilds/{guildId}/shop/items
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 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | integer | 是 | |
items[].storeId | integer | null | 是 | null = Main store |
items[].name | string | 是 | |
items[].description | string | null | 是 | |
items[].emoji | string | null | 是 | |
items[].price | integer | 是 | |
items[].type | string | 是 | 其中之一 role, color, item |
items[].category | string | null | 是 | |
items[].roleId | string | null | 是 | |
items[].durationSec | integer | 是 | Timed role length; 0 = permanent |
items[].consumable | boolean | 是 | |
items[].fulfillment | boolean | 是 | Staff deliver it (fulfilment request) |
items[].stock | integer | null | 是 | null = unlimited |
items[].perUserLimit | integer | null | 是 | |
items[].requiredRoleIds | array of string | 是 | |
items[].minLevel | integer | 是 | |
items[].enabled | boolean | 是 | |
items[].hidden | boolean | 是 | |
items[].sortOrder | integer | 是 | |
currency | object | 是 | |
currency.name | string | 是 | |
currency.plural | string | 是 | |
currency.emoji | string | null | 是 |
{
"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)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Get an item
GET/guilds/{guildId}/shop/items/{itemId}
需要在伺服器上啟用此功能: 商店
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
itemId | 路徑 | string | 是 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
id | integer | 是 | |
storeId | integer | null | 是 | null = Main store |
name | string | 是 | |
description | string | null | 是 | |
emoji | string | null | 是 | |
price | integer | 是 | |
type | string | 是 | 其中之一 role, color, item |
category | string | null | 是 | |
roleId | string | null | 是 | |
durationSec | integer | 是 | Timed role length; 0 = permanent |
consumable | boolean | 是 | |
fulfillment | boolean | 是 | Staff deliver it (fulfilment request) |
stock | integer | null | 是 | null = unlimited |
perUserLimit | integer | null | 是 | |
requiredRoleIds | array of string | 是 | |
minLevel | integer | 是 | |
enabled | boolean | 是 | |
hidden | boolean | 是 | |
sortOrder | integer | 是 |
{
"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)錯誤
| HTTP | 代碼 |
|---|---|
| 404 | SHOP_ITEM_NOT_FOUND |
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Restock or turn an item on/off
PATCH/guilds/{guildId}/shop/items/{itemId}
Like /shopadmin restock and toggle. Send stock (null = unlimited) and/or enabled.
需要在伺服器上啟用此功能: 商店
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
itemId | 路徑 | string | 是 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
enabled | boolean | 否 | Off = not listed, not buyable |
stock | integer | null | 否 | New stock; null = unlimited 0–1,000,000 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
id | integer | 是 | |
storeId | integer | null | 是 | null = Main store |
name | string | 是 | |
description | string | null | 是 | |
emoji | string | null | 是 | |
price | integer | 是 | |
type | string | 是 | 其中之一 role, color, item |
category | string | null | 是 | |
roleId | string | null | 是 | |
durationSec | integer | 是 | Timed role length; 0 = permanent |
consumable | boolean | 是 | |
fulfillment | boolean | 是 | Staff deliver it (fulfilment request) |
stock | integer | null | 是 | null = unlimited |
perUserLimit | integer | null | 是 | |
requiredRoleIds | array of string | 是 | |
minLevel | integer | 是 | |
enabled | boolean | 是 | |
hidden | boolean | 是 | |
sortOrder | integer | 是 |
{
"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)錯誤
A member’s inventory
GET/guilds/{guildId}/shop/members/{userId}/inventory
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(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | integer | 是 | |
items[].itemId | integer | null | 是 | null when the item was deleted (the snapshot stays) |
items[].storeId | integer | null | 是 | |
items[].storeName | string | null | 是 | |
items[].itemName | string | 是 | |
items[].itemEmoji | string | null | 是 | |
items[].itemType | string | 是 | |
items[].userId | string | 是 | |
items[].price | integer | 是 | 0 for free grants |
items[].status | string | 是 | 其中之一 owned, used, refunded |
items[].roleId | string | null | 是 | |
items[].expiresAt | string | null | 是 | |
items[].roleRemovedAt | string | null | 是 | |
items[].fulfillment | string | 是 | 其中之一 none, pending, done |
items[].bankTransactionId | integer | null | 是 | |
items[].refundTransactionId | integer | null | 是 | |
items[].usedAt | string | null | 是 | |
items[].refundedAt | string | null | 是 | |
items[].createdAt | string | 是 | |
items[].roleActive | boolean | 是 |
{
"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)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
List purchases
GET/guilds/{guildId}/shop/purchases
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 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].id | integer | 是 | |
items[].itemId | integer | null | 是 | null when the item was deleted (the snapshot stays) |
items[].storeId | integer | null | 是 | |
items[].storeName | string | null | 是 | |
items[].itemName | string | 是 | |
items[].itemEmoji | string | null | 是 | |
items[].itemType | string | 是 | |
items[].userId | string | 是 | |
items[].price | integer | 是 | 0 for free grants |
items[].status | string | 是 | 其中之一 owned, used, refunded |
items[].roleId | string | null | 是 | |
items[].expiresAt | string | null | 是 | |
items[].roleRemovedAt | string | null | 是 | |
items[].fulfillment | string | 是 | 其中之一 none, pending, done |
items[].bankTransactionId | integer | null | 是 | |
items[].refundTransactionId | integer | null | 是 | |
items[].usedAt | string | null | 是 | |
items[].refundedAt | string | null | 是 | |
items[].createdAt | string | 是 | |
nextCursor | string | null | 是 |
{
"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)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Get a purchase
GET/guilds/{guildId}/shop/purchases/{purchaseId}
需要在伺服器上啟用此功能: 商店
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
purchaseId | 路徑 | string | 是 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
id | integer | 是 | |
itemId | integer | null | 是 | null when the item was deleted (the snapshot stays) |
storeId | integer | null | 是 | |
storeName | string | null | 是 | |
itemName | string | 是 | |
itemEmoji | string | null | 是 | |
itemType | string | 是 | |
userId | string | 是 | |
price | integer | 是 | 0 for free grants |
status | string | 是 | 其中之一 owned, used, refunded |
roleId | string | null | 是 | |
expiresAt | string | null | 是 | |
roleRemovedAt | string | null | 是 | |
fulfillment | string | 是 | 其中之一 none, pending, done |
bankTransactionId | integer | null | 是 | |
refundTransactionId | integer | null | 是 | |
usedAt | string | null | 是 | |
refundedAt | string | null | 是 | |
createdAt | string | 是 |
{
"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)錯誤
| HTTP | 代碼 |
|---|---|
| 404 | SHOP_PURCHASE_NOT_FOUND |
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Buy an item for a member
POST/guilds/{guildId}/shop/members/{userId}/purchases
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),重試時沿用同一個值,變更就只會發生一次。 運作方式 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
itemId | integer | 是 | 至少 1 |
expectedPrice | integer | 否 | Refused with SHOP_ITEM_UNAVAILABLE (price_changed) when the price differs 0–1,000,000,000 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
purchase | object | 是 | |
purchase.id | integer | 是 | |
purchase.itemId | integer | null | 是 | null when the item was deleted (the snapshot stays) |
purchase.storeId | integer | null | 是 | |
purchase.storeName | string | null | 是 | |
purchase.itemName | string | 是 | |
purchase.itemEmoji | string | null | 是 | |
purchase.itemType | string | 是 | |
purchase.userId | string | 是 | |
purchase.price | integer | 是 | 0 for free grants |
purchase.status | string | 是 | 其中之一 owned, used, refunded |
purchase.roleId | string | null | 是 | |
purchase.expiresAt | string | null | 是 | |
purchase.roleRemovedAt | string | null | 是 | |
purchase.fulfillment | string | 是 | 其中之一 none, pending, done |
purchase.bankTransactionId | integer | null | 是 | |
purchase.refundTransactionId | integer | null | 是 | |
purchase.usedAt | string | null | 是 | |
purchase.refundedAt | string | null | 是 | |
purchase.createdAt | string | 是 | |
balance | integer | null | 是 | The member’s balance afterwards (null when unchanged) |
{
"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)錯誤
Give an item to a member for free
POST/guilds/{guildId}/shop/members/{userId}/grants
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),重試時沿用同一個值,變更就只會發生一次。 運作方式 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
itemId | integer | 是 | 至少 1 |
reason | string | null | 否 | Shown in the audit log 最多 200 個字元 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
purchase | object | 是 | |
purchase.id | integer | 是 | |
purchase.itemId | integer | null | 是 | null when the item was deleted (the snapshot stays) |
purchase.storeId | integer | null | 是 | |
purchase.storeName | string | null | 是 | |
purchase.itemName | string | 是 | |
purchase.itemEmoji | string | null | 是 | |
purchase.itemType | string | 是 | |
purchase.userId | string | 是 | |
purchase.price | integer | 是 | 0 for free grants |
purchase.status | string | 是 | 其中之一 owned, used, refunded |
purchase.roleId | string | null | 是 | |
purchase.expiresAt | string | null | 是 | |
purchase.roleRemovedAt | string | null | 是 | |
purchase.fulfillment | string | 是 | 其中之一 none, pending, done |
purchase.bankTransactionId | integer | null | 是 | |
purchase.refundTransactionId | integer | null | 是 | |
purchase.usedAt | string | null | 是 | |
purchase.refundedAt | string | null | 是 | |
purchase.createdAt | string | 是 | |
balance | integer | null | 是 | The member’s balance afterwards (null when unchanged) |
{
"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)錯誤
Refund a purchase
POST/guilds/{guildId}/shop/purchases/{purchaseId}/refund
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),重試時沿用同一個值,變更就只會發生一次。 運作方式 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
restock | boolean | 否 | Put the unit back in stock (default: the Shop’s “restock on refund” setting) |
force | boolean | 否 | Also refund an item that was already used |
reason | string | null | 否 | Shown in the audit log 最多 200 個字元 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
purchase | object | 是 | |
purchase.id | integer | 是 | |
purchase.itemId | integer | null | 是 | null when the item was deleted (the snapshot stays) |
purchase.storeId | integer | null | 是 | |
purchase.storeName | string | null | 是 | |
purchase.itemName | string | 是 | |
purchase.itemEmoji | string | null | 是 | |
purchase.itemType | string | 是 | |
purchase.userId | string | 是 | |
purchase.price | integer | 是 | 0 for free grants |
purchase.status | string | 是 | 其中之一 owned, used, refunded |
purchase.roleId | string | null | 是 | |
purchase.expiresAt | string | null | 是 | |
purchase.roleRemovedAt | string | null | 是 | |
purchase.fulfillment | string | 是 | 其中之一 none, pending, done |
purchase.bankTransactionId | integer | null | 是 | |
purchase.refundTransactionId | integer | null | 是 | |
purchase.usedAt | string | null | 是 | |
purchase.refundedAt | string | null | 是 | |
purchase.createdAt | string | 是 | |
balance | integer | null | 是 | The member’s balance afterwards (null when unchanged) |
{
"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)