Shop
The Shop API lets server owners set up stores with categories, products, cart, orders, reviews, and a wallet system.
Get / Create shop
GET /api/servers/:serverId/shop
Returns the shop for the server, creating one if it doesn't exist.
const shop = await client.getShop('server-id')
shop = client.get_shop("server-id")
Update shop
PUT /api/servers/:serverId/shop
await client.updateShop('server-id', { name: 'My Store' })
client.update_shop("server-id", name="My Store")
Categories
List categories
GET /api/servers/:serverId/shop/categories
const categories = await client.listCategories('server-id')
categories = client.list_categories("server-id")
Create category
POST /api/servers/:serverId/shop/categories
const category = await client.createCategory('server-id', {
name: 'Merch',
description: 'Official merchandise',
})
category = client.create_category("server-id", name="Merch", description="Official merchandise")
Update category
PUT /api/servers/:serverId/shop/categories/:categoryId
await client.updateCategory('server-id', 'category-id', { name: 'Accessories' })
client.update_category("server-id", "category-id", name="Accessories")
Delete category
DELETE /api/servers/:serverId/shop/categories/:categoryId
await client.deleteCategory('server-id', 'category-id')
client.delete_category("server-id", "category-id")
Products
List products
GET /api/servers/:serverId/shop/products
| Param | Type | Description |
|---|
status | string | Filter by status |
categoryId | string | Filter by category |
keyword | string | Search keyword |
limit | number | Max results |
offset | number | Offset |
const products = await client.listProducts('server-id', { keyword: 'shirt' })
products = client.list_products("server-id", keyword="shirt")
Get product
GET /api/servers/:serverId/shop/products/:productId
const product = await client.getProduct('server-id', 'product-id')
product = client.get_product("server-id", "product-id")
Create product
POST /api/servers/:serverId/shop/products
const product = await client.createProduct('server-id', {
name: 'T-Shirt',
categoryId: 'category-id',
price: 25.99,
})
product = client.create_product("server-id", name="T-Shirt", categoryId="category-id", price=25.99)
Update product
PUT /api/servers/:serverId/shop/products/:productId
await client.updateProduct('server-id', 'product-id', { price: 19.99 })
client.update_product("server-id", "product-id", price=19.99)
Delete product
DELETE /api/servers/:serverId/shop/products/:productId
await client.deleteProduct('server-id', 'product-id')
client.delete_product("server-id", "product-id")
Cart
Get cart
GET /api/servers/:serverId/shop/cart
const cart = await client.getCart('server-id')
cart = client.get_cart("server-id")
Add to cart
POST /api/servers/:serverId/shop/cart
| Field | Type | Required | Description |
|---|
productId | string | Yes | Product ID |
skuId | string | No | SKU variant |
quantity | number | Yes | Quantity |
await client.addToCart('server-id', {
productId: 'product-id',
quantity: 2,
})
client.add_to_cart("server-id", productId="product-id", quantity=2)
Update cart item
PUT /api/servers/:serverId/shop/cart/:itemId
await client.updateCartItem('server-id', 'item-id', 3)
client.update_cart_item("server-id", "item-id", quantity=3)
Remove from cart
DELETE /api/servers/:serverId/shop/cart/:itemId
await client.removeFromCart('server-id', 'item-id')
client.remove_from_cart("server-id", "item-id")
Orders
Place order
POST /api/servers/:serverId/shop/orders
| Field | Type | Required | Description |
|---|
items | array | Yes | Cart item IDs or product specs |
buyerNote | string | No | Note to seller |
const order = await client.placeOrder('server-id', {
items: [{ productId: 'pid', quantity: 1 }],
buyerNote: 'Please gift-wrap',
})
order = client.place_order("server-id", items=[{"productId": "pid", "quantity": 1}], buyerNote="Please gift-wrap")
List my orders
GET /api/servers/:serverId/shop/orders
const orders = await client.listOrders('server-id', { status: 'paid' })
orders = client.list_orders("server-id", status="paid")
Admin: manage orders
GET /api/servers/:serverId/shop/orders/manage
const orders = await client.manageOrders('server-id', { status: 'pending' })
orders = client.manage_orders("server-id", status="pending")
Get order
GET /api/servers/:serverId/shop/orders/:orderId
const order = await client.getOrder('server-id', 'order-id')
order = client.get_order("server-id", "order-id")
Update order status
PUT /api/servers/:serverId/shop/orders/:orderId/status
| Field | Type | Required | Description |
|---|
status | string | Yes | New status |
trackingNo | string | No | Tracking number |
sellerNote | string | No | Note to buyer |
await client.updateOrderStatus('server-id', 'order-id', {
status: 'shipped',
trackingNo: 'TRACK123',
})
client.update_order_status("server-id", "order-id", status="shipped", trackingNo="TRACK123")
Cancel order
POST /api/servers/:serverId/shop/orders/:orderId/cancel
await client.cancelOrder('server-id', 'order-id')
client.cancel_order("server-id", "order-id")
Reviews
List product reviews
GET /api/servers/:serverId/shop/products/:productId/reviews
const reviews = await client.listProductReviews('server-id', 'product-id')
reviews = client.list_product_reviews("server-id", "product-id")
Submit review
POST /api/servers/:serverId/shop/orders/:orderId/review
| Field | Type | Required | Description |
|---|
productId | string | Yes | Product reviewed |
rating | number | Yes | 1 – 5 |
content | string | No | Review text |
images | string[] | No | Image URLs |
isAnonymous | boolean | No | Post anonymously |
await client.submitReview('server-id', 'order-id', {
productId: 'product-id',
rating: 5,
content: 'Excellent quality!',
})
client.submit_review("server-id", "order-id", productId="product-id", rating=5, content="Excellent quality!")
Reply to review (seller)
PUT /api/servers/:serverId/shop/reviews/:reviewId/reply
await client.replyToReview('server-id', 'review-id', 'Thank you!')
client.reply_to_review("server-id", "review-id", reply="Thank you!")
Wallet
Get wallet
const wallet = await client.getWallet()
wallet = client.get_wallet()
Top up
| Field | Type | Required | Description |
|---|
amount | number | Yes | Amount to add |
note | string | No | Note |
await client.topUpWallet(100, 'Monthly deposit')
client.top_up_wallet(100, note="Monthly deposit")
List transactions
GET /api/wallet/transactions
const txns = await client.listTransactions({ limit: 50 })
txns = client.list_transactions(limit=50)
Entitlements
GET /api/servers/:serverId/shop/entitlements
const entitlements = await client.listEntitlements('server-id')
entitlements = client.list_entitlements("server-id")
