From catalog
to delivery.

1. Create your key

   In the bot, open Profile → API key → Create my API key.

2. Set up your environment

   Store the key as API_KEY on your server. Set BASE_URL to this website’s origin, without a trailing slash.

3. Check your balance

   Run the request below or connect on the API test page. Viewing your balance and catalog is free.

curl "$BASE_URL/api/v1/me?currency=USD" \
  -H "Authorization: Bearer $API_KEY"

Include your key in every request header. It grants access only to its owner’s balance and orders.

Authorization: Bearer YOUR_API_KEY

The X-API-Key header is also supported. Keys in the URL are not accepted.

Returns your Telegram ID, username, balance and request limit. You share the same balance with the bot; top up from your profile.

{
  "id": 42,
  "name": "Example product",
  "price_kopeks": 19900,
  "price": "199.00",
  "currency": "RUB",
  "stock": 12,
  "stock_unlimited": false,
  "available": true,
  "category": {
    "id": 3,
    "name": "Subscriptions"
  },
  "wholesale_tiers": [
    {
      "min_quantity": 5,
      "unit_price_kopeks": 17900,
      "unit_price": "179.00",
      "currency": "RUB"
    }
  ]
}

Refresh the catalog within your request limit; changes are not pushed automatically. For stock_unlimited=true, stock is null and does not run out. Services requiring extra parameters are purchased in the bot.

Add currency=RUB or currency=USD to balance, catalog, order and transaction requests. RUB is the default. Language and currency are independent; no separate USD wallet is created.

{
  "currency": "USD",
  "settlement_currency": "RUB",
  "exchange_rate": {
    "base": "USD",
    "quote": "RUB",
    "rate": "80",
    "updated_at": "2026-09-20T12:00:00.000Z"
  },
  "items": [
    {
      "id": 42,
      "price_kopeks": 19900,
      "price": "2.49",
      "currency": "USD"
    }
  ]
}

The server determines the price. max_total_kopeks caps spending; it does not set the price. price, currency and exchange_rate are not accepted in the order body. Response currency never changes the charge.

USD history uses the current response’s rate. Save the response and rate for a snapshot at request time. If the rate is unavailable, USD returns 503 exchange_rate_unavailable before creating an order; retry in RUB with the same idempotency key.

Each response includes the language selected with lang, in two formats without shop-specific formatting commands.

{
  "description": "Product description\nGuide (https://example.com/guide)",
  "description_html": "<strong>Product description</strong><br><a href=\"https://example.com/guide\" rel=\"noopener noreferrer\">Guide</a>"
}

delivery_data is passed through unchanged. Preserve it in full, including line breaks.

One request creates an order for 1–100 units of one product. This charges the key owner’s balance. Save the idempotency key and parameters before sending.

curl -X POST "$BASE_URL/api/v1/orders?currency=USD" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: store-order-1042" \
  -d '{
    "product_id": 42,
    "quantity": 1,
    "max_total_kopeks": 19900,
    "client_order_id": "1042"
  }'

Deliver to your customer only when status=delivered. data.delivery_data contains the complete payload: text, multiple lines or JSON encoded as a string.

The test product is available to every API client. Find is_test=true in the catalog and use its id. Stock is unlimited: stock=null, stock_unlimited=true, available=true; api_only=true.

1. Send a standard POST /orders with the test product ID, quantity=1 and max_total_kopeks=100.
2. Wait for delivered and save delivery_data. Reuse the same Idempotency-Key if you retry.

The website guides you through confirmation, result checking, and copying or downloading delivery. Your API key stays in tab memory; only the operation identity is saved for recovery.

If the response is lost, repeat the original POST with the same Idempotency-Key and parameters. A new key creates a new purchase; changing the original parameters returns 409 idempotency_conflict. Changing the response currency does not create a new order.

Once you know the ID, check that order with GET no more than once every 5 seconds.

The key owner’s API orders. Filter by client_order_id to find your reference. Lists omit delivery data; request the individual order by ID.

All transactions on your balance. amount_kopeks is signed: positive for credits, negative for charges or holds. purchase_hold becomes purchase after delivery; purchase_refund is a return.

Both lists accept limit from 1 to 100. has_more indicates another page. Use currency=RUB or currency=USD for display amounts.

{
  "ok": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Your available balance is too low."
  }
}

Handle error.code rather than message text. A purchase error may still include order data. Keep the same idempotency key after network errors or 5xx responses.