The BotSubscription API

This REST API provides endpoints for managing projects, users, subscriptions, payments, and related resources. All endpoints require authentication unless explicitly specified otherwise.

Quick reference

Authentication

Include your authentication token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Language Selection

Specify the language for translated messages by sending an Accept-Language header:

Accept-Language: bg

If the header is omitted, English (en) is used.

Common Response Format

All API responses follow this format:

{
  "request_id": "uuid",
  "method": "HTTP_METHOD",
  "path": "/api/path",
  "code": 200,
  "data": {} // or [] for list responses
}

Error Responses

Error responses follow this format:

{
  "request_id": "uuid",
  "method": "HTTP_METHOD",
  "path": "/api/path",
  "code": 400,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

Error Codes

Pagination

List endpoints support pagination using the following query parameters:

Live Updates (WebSocket)

For real-time updates, connect to the WebSocket endpoint using a Socket.IO client:

• Path: wss://<api-host>/live-updates/{project_id}
• Purpose: Push realtime events such as payment request updates
• Client: Requires Socket.IO client library (available for JavaScript, Python, PHP, etc.)

Outbound Webhooks (Real-Time Events)

For server-to-server integrations, BotSubscription supports outbound webhooks. You can register HTTPS POST endpoints per project to receive real-time notifications for payment completion and other platform events.

To get started, see our comprehensive Webhooks Overview or explore active events like payment-request.completed.

Health Check

• GET /ping
• No authentication required
• Returns: { "ok": true }