Quick start

Shop API supports Telegram Stars, Telegram Premium, game/account topups and digital codes. All requests are server-to-server JSON requests; all amounts are in USD.

:::info Publication before launch

This documentation describes the implemented API. Public deployment and end-to-end production testing are the next stage. IDs, product names and prices in examples are illustrative; obtain actual values from the catalog.

:::

1. Prepare the integration

In the dashboard, create a Shop API integration and open its settings. You need:

• api_key_id — the numeric integration ID.
• X-Api-Key — the secret API key.

Top up the integration balance before buying. Keep the API key on your backend, not in a browser, public repository or application distributed to customers. Resetting the key in the dashboard replaces the key used for subsequent requests.

2. Check the balance

Base URL: https://shop-api.adaptgroup.pro.

All ten public endpoints use POST, Content-Type: application/json, the X-Api-Key header and api_key_id in the JSON body.

curl --request POST 'https://shop-api.adaptgroup.pro/balance/check' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{"api_key_id":1}'

Example response:

{
  "success": true,
  "api_key_id": 1,
  "balance": "25.0000",
  "currency": "USD",
  "balance_updated_at": "2026-09-26T12:00:00"
}

Amounts are decimal strings. Use decimal arithmetic, not binary floating-point calculations. Timestamps are UTC; order and balance timestamps may be returned without a timezone suffix.

3. Choose a module

Module	What you buy	Where to get parameters
stars	50–100000 Telegram Stars	Price per Star from /modules/list; recipient username
tg_premium	Telegram Premium for 3, 6 or 12 months	Prices from /modules/list; recipient username
topups	A game/account topup nominal	/catalog/list → /catalog/details → /catalog/nominal
codes	A digital code nominal	Same catalog routes; no recipient required

The catalog exposes products configured on the platform, not a supplier's entire catalog. item_id identifies a product; nominal_id identifies one denomination under that product. Use the identifiers returned by this API.

4. Check, calculate and buy

1. Collect the recipient data for Stars, Premium or topups and call Check recipient. Skip this step for codes.
2. Call Calculate price to show the current total.
3. Call Create order once for the intended purchase. The current price is charged automatically; do not send a price.
4. Save the returned order_id. Retrieve the result via Order status or Webhooks.

See Purchase flow for module-specific examples, field selection and uncertain results.

Limits and errors

The integration has a shared limit of 100 requests per 60 seconds across all public endpoints. Separate integrations have separate counters. A limit error returns HTTP 429; there is no separate per-route quota.

Unknown request fields are rejected. Send integers as JSON numbers and customer/recipient identifiers as strings where specified. Request variants are selected by module.

HTTP status	Meaning
200	Operation returned a result. Inspect success, status, valid and supported as applicable
400	Business refusal: insufficient balance, unavailable nominal, invalid recipient or quantity
401	Missing/invalid key, wrong integration ID or inactive integration
404	Requested product, nominal or order not found
422	Request validation failed
429	Rate limit exceeded
500	Unexpected server error
502, 503, 504	Invalid upstream response, temporary unavailability or timeout

Most errors have a string detail:

{"detail":"Insufficient balance"}

Validation errors have a detail array:

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "api_key_id"],
      "msg": "Input should be greater than or equal to 1",
      "input": 0,
      "ctx": {"ge": 1}
    }
  ]
}

A creation error can instead contain detail.order_id. Preserve it and check that order. Do not automatically replay a purchase after a timeout, network failure or uncertain response. See Purchase flow.

API specification

Download OpenAPI in English · Download OpenAPI in Russian

Both files describe the same routes, fields and constraints. Only the documentation language differs; there is no language parameter in public API requests.