API Documentation

REST over HTTPS. All responses are JSON. Requests are relayed to the GenBoost Store bot and answered in real time.

Base URL

https://genbooststore.shop/api/public/v1

Authentication

Send your reseller key on every request. Both header styles work:

X-API-Key: gb_live_xxxxxxxxxxxx
# or
Authorization: Bearer gb_live_xxxxxxxxxxxx

Quick start

curl -s "https://genbooststore.shop/api/public/v1/products?page=1" \
  -H "X-API-Key: $GB_KEY"

curl -s -X POST "https://genbooststore.shop/api/public/v1/orders" \
  -H "X-API-Key: $GB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{"product_id": 12, "quantity": 1}'

Endpoints

GET
/ping

Health check. Confirms the gateway reached the bot.

GET
/me

Reseller profile tied to the API key (name, markup, limits).

GET
/balance

Current wallet balance and currency.

GET
/categories

All active categories.

GET
/products?category_id=&search=&page=

Paginated product list with reseller pricing applied.

GET
/products/{id}

Single product with stock and price.

POST
/orders

Place an order. Balance is debited instantly; send Idempotency-Key to avoid duplicates.

{
  "product_id": 12,
  "quantity": 1,
  "order_ref": "your-internal-id"
}
GET
/orders?page=&limit=

Your order history.

GET
/orders/{id}

Single order status and delivered content.

Premium (custom) emojis

Category names, product names and descriptions use Telegram Premium custom emojis. Every product and category object ships the exact emoji IDs, so your bot renders the same emoji instead of a random fallback. They only render if the owner of your bot has Telegram Premium — otherwise users simply see the normal emoji.

{
  "id": 12,
  "name": "🔥 ChatGPT Plus",
  "name_html": "<tg-emoji emoji-id=\"6053163053980063912\">🔥</tg-emoji> ChatGPT Plus",
  "name_entities": [
    { "type": "custom_emoji", "offset": 0, "length": 2,
      "custom_emoji_id": "6053163053980063912" }
  ],
  "description_html": "...", "description_entities": [ ... ],
  "category_html": "...",    "category_entities": [ ... ],
  "custom_emojis": ["6053163053980063912"]
}

Option A — HTML

await bot.send_message(
    chat_id,
    f"{product['name_html']}\n\n{product['description_html']}",
    parse_mode="HTML",
)

Option B — entities

from telegram import MessageEntity

entities = [MessageEntity(**e) for e in product["name_entities"]]
await bot.send_message(chat_id, product["name"], entities=entities)
  • Offsets are UTF-16 code units — pair them with the plain field.
  • Concatenating fields? Shift offsets by the UTF-16 length of the text you prepend, or just use the _html fields.
  • Inline button labels can never show custom emojis (Telegram limit).

Errors

{ "ok": false, "error": "INSUFFICIENT_BALANCE", "message": "..." }
  • 401 UNAUTHORIZED — missing or invalid API key
  • 402 INSUFFICIENT_BALANCE — top up your wallet
  • 404 NOT_FOUND — unknown product or order
  • 409 OUT_OF_STOCK — not enough stock
  • 503 BOT_OFFLINE — bot server is not reachable