Telegram Premium API for gift subscriptions

Check recipient eligibility, select a live Premium package, create one idempotent gift order, and track the result from your backend or Fragment API dashboard.

Get an API key Open API documentation

Durations: 3, 6, or 12 months
Settlement: TON or USDT on TON
Pricing: Live package values
Delivery: Asynchronous order state

What this API is for

Use the Telegram Premium API when your application needs to gift a supported Premium subscription to a Telegram username. The package endpoint provides current display pricing, while recipient search validates the username for the selected duration and returns the hash required to create the order.

Fragment API is designed for server-side integrations. Your API key stays on your backend; your application sends a recipient search request, creates the order, stores its ID, and confirms the final result. The public contract is available as an OpenAPI document for code generators and AI coding tools.

This is a purchasing and gifting API. It is different from the Telegram Bot API flow for accepting Stars as payment inside a bot or Mini App. Use the product that matches the direction of value in your application.

Integration flow

Keep these steps in order so recipient validation, wallet reservation, and delivery state remain consistent.

01
Read current packages
Call GET /premium/packages to show current 3, 6, and 12 month presentation values before checkout.
02
Validate the recipient
Call GET /premium/recipient/search with the Telegram username and chosen number of months. Use the returned recipient hash for this order.
03
Create the Premium gift
POST the username, recipient hash, months, and wallet type with a unique Idempotency-Key.
04
Wait for the final state
Store the order_id and confirm completed or failed through signed webhooks and status polling.

Create the order

The order call is asynchronous. A successful response reserves the amount and returns an order ID; it does not mean delivery is final.

POST /orders/premiumbash

curl -X POST "https://v1.fragmentapi.com/api/v1/partner/orders/premium" \
  -H "API-Key: $FRAGMENT_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alexdev",
    "recipient_hash": "hash_from_recipient_search",
    "months": 3,
    "wallet_type": "USDT"
  }'

Production decisions that matter

Eligibility belongs to the selected duration

Run recipient search with the same month value you will use for the order. Do not reuse a hash gathered for a different package.

Live package values are for display

The amount returned by the created order is the authoritative charge because provider prices can change between catalog display and purchase.

Keep the API key on your server

Never expose the developer key in browser JavaScript, a Telegram Mini App bundle, or a mobile client. Proxy purchase requests through your backend.

Use final status for fulfillment

A pending or processing order has not yet completed. Only mark the customer purchase delivered after the API reports completed.

Frequently asked questions

Telegram's official Premium reference

Which Telegram Premium durations are supported?

Fragment API supports the provider's available 3, 6, and 12 month Premium gift packages.

Can I gift Premium to every Telegram account?

Eligibility depends on the provider and selected package. Use the recipient-search endpoint immediately before creating the order.

Where do I get current Premium pricing?

Call GET /premium/packages for display values. The amount in the created order response is the authoritative amount reserved from your chosen balance.

Can I pay from a USDT balance?

Accounts with USDT enabled can select official USDT on the TON network. TON and USDT remain separate developer balances.

How should I recover after a timeout?

Retry the same request with the same Idempotency-Key. Then read the returned or existing order by ID instead of starting a new logical purchase.