Question 1

Can I offer weekly or annual Star Subscriptions?

Accepted Answer

No. As of Bot API 8.0 the only supported subscription_period is 2592000 (30 days). Plan pricing around the monthly cycle and revisit when Telegram extends the spec.

Question 2

What is the maximum I can charge per subscription?

Accepted Answer

10,000 Telegram Stars per 30-day period — about $130 at point-of-sale rates. The same ceiling applies whether the subscription gates a Mini App, a private channel, or bot-mediated content access.

Question 3

How do I handle subscription upgrades and downgrades?

Accepted Answer

There is no in-place tier change. Cancel the existing subscription with editUserStarSubscription(is_canceled=True), then send a fresh invoice link for the new tier. The old tier remains active until its current period ends; the new tier starts billing immediately.

Question 4

Does Telegram notify the user when the bot cancels their subscription?

Accepted Answer

No. editUserStarSubscription(is_canceled=True) is silent — the user only finds out when the next renewal does not happen. Send your own confirmation, and show a "subscription ends on YYYY-MM-DD" line in any post-cancel UI.

Question 5

How do I tell the first payment from a renewal in `successful_payment`?

Accepted Answer

Bot API 8.0 added is_first_recurring (true exactly once per subscription) and is_recurring (true on every charge after the first). A one-shot Stars payment has both flags missing or false. Branch handlers on these flags, not on invoice_payload matching alone.

Question 6

Can a user cancel without my bot being involved?

Accepted Answer

Yes. Subscribers can manage every Star Subscription in Settings → Telegram Stars → Subscriptions. Your bot is not notified — the only signal is that the next renewal does not arrive. Treat any subscription past expires_at + 24h as canceled in your access layer.