Telegram Stars subscriptions in mini apps: how to build the business model
How to plan a Telegram Stars subscription for a mini app or bot: value, tiers, pricing, retention and payouts, within the limits of the Bot API.
Published:

A one-off purchase pays once. A subscription pays every month. That's why Telegram's big mini app update in November 2024 gave developers Telegram Stars subscriptions in mini apps: a monthly payment for tiered content and features. This guide isn't about the technical integration, which is covered in our XTR invoice guide. It's about building the model.
1. Value: why people pay every month
A subscription only works if the value keeps coming back: new content, higher limits, a bundle of AI requests, an ad-free mode. One-off value wrapped up as a subscription usually gets cancelled fast.
2. Tiers
The Bot API allows one user to hold several concurrent subscriptions, so tiers are easy to build with separate invoice links.
| Tier | What it gives | Who it's for |
|---|---|---|
| Basic | Higher core limits | People trying it out |
| Pro | Every feature | Active users |
| Team / add-on pack | A separate subscription | Power users |
3. Price and technical limits
| Parameter | Bot API rule |
|---|---|
| Currency | XTR (Telegram Stars) |
| subscription_period | Currently only 2592000 (30 days) |
| Maximum price | 10000 Stars |
| Renewal flags | is_recurring, is_first_recurring |
| Expiry | subscription_expiration_date |
When you set a price, consider what Stars cost your users. See how to buy Stars and Premium with USDT.
4. Retention
- Track the first payment (is_first_recurring) separately, because it shows how well onboarding works.
- Send a reminder before the period ends.
- Let people who cancelled come back via editUserStarSubscription.
- Answer /paysupport quickly, since Telegram requires developers to provide timely support.
5. Revenue
Earned Stars can be spent on Telegram Ads or exchanged for rewards through Fragment. There's a waiting period before you can claim them: see the 21-day hold.
The user's side
If subscribers keep a reserve of Stars, renewals don't get interrupted. As a mini app owner, you can point them to where to buy Stars: on PayStars with USDT, from 50 Stars. If you need to hand out Stars to many users, see the PayStars API.
FAQ
Can I price a subscription in dollars?
For digital goods the currency must be XTR (Telegram Stars). You can mention the dollar equivalent in the description.
Can the bot cancel a subscription itself?
Yes. The Bot API has editUserStarSubscription, which lets a bot cancel or re-enable a user's subscription.
How do I recognise a renewal payment?
successful_payment includes the is_recurring and is_first_recurring fields, plus subscription_expiration_date.
Sources
Buy Stars and Premium with USD (USDT)
Via API key: 0% (plain Fragment price). Via the website: 5%.
More news
Writing a refund policy for your Telegram Stars bot: template and examplesWhat a refund policy for a Telegram Stars bot should cover: eligibility, time window, /paysupport and refundStarPayment, plus sample wording you can adapt.Read →
What happens to your Telegram Stars if you lose access to your accountStars belong to your Telegram account, not your phone. Learn what happens to them when you lose access, how to get back in, and how to protect your balance.Read →
Keeping records of Telegram Stars revenue as a creator or businessHow to keep clean records of Telegram Stars revenue: what to log, tracking Fragment withdrawals, separating personal and business, and what to ask an accountant.Read →