The short answer
- 1Subscriptions are Stars (XTR) only, one 30-day period, up to 10,000 Stars.
- 2Add subscription_period to createInvoiceLink to get a subscription link.
- 3Track renewals from successful_payment fields and store each user's expiry.
In this article
What a Star subscription is
A bot can charge users a monthly payment in Telegram Stars. After the first payment, the subscription renews automatically from the user's Stars balance at the end of each period, until the user cancels. Bots selling digital goods or services must take payment in Stars under app store rules. For how subscriptions look to the person paying, see how Telegram Star subscriptions work.
| Rule | Detail (official documentation) |
|---|---|
| Currency | XTR (Telegram Stars) only |
| Period | Currently only 30 days (2592000 seconds) |
| Price | Up to 10,000 Stars per period |
| Several at once | A bot can run several subscriptions, and the same user can hold more than one |
Create the payment link
Add subscription_period to createInvoiceLink and the link becomes a subscription. Open it from a button or from your mini app.
curl https://api.telegram.org/bot123456:ABC-EXAMPLE/createInvoiceLink \
-H "Content-Type: application/json" \
-d '{"title":"Pro features","description":"No ads, unlimited use",
"payload":"sub_basic","currency":"XTR",
"prices":[{"label":"One month","amount":100}],
"subscription_period":2592000}'Payments in Stars need no provider_token. The price and token here are examples; see your first Bot API requests.
Recognise payments and renewals
When a payment completes, your bot receives a message with successful_payment. For a subscription it carries extra fields:
| Field | Meaning |
|---|---|
is_recurring | This is a subscription payment |
is_first_recurring | The first payment of that subscription; absent on renewals |
subscription_expiration_date | The last moment this payment covers, in Unix time |
telegram_payment_charge_id | The payment's ID; store it, you need it to cancel or refund |
Store an expiry time for each user on your server and check it whenever you unlock a feature. When a renewal arrives, replace the expiry time with the new value.
Cancel, resume and refund
editUserStarSubscriptionstops a user's next renewal (cancel) or lets it continue again (resume). It needs the user ID and the payment ID.refundStarPaymentrefunds a single payment.
Users can also see and cancel their subscriptions in the Stars section of their own Telegram settings. After cancelling, they keep access until the period they paid for ends.
To turn earned Stars into money, see withdrawing Stars earnings. Channels can use the same 30-day model for paid invite links with createChatSubscriptionInviteLink: a private channel people enter by paying the subscription.
FAQ
How do I create a Stars subscription for my Telegram bot?
Call createInvoiceLink with currency XTR, a price and subscription_period set to 2592000 seconds.
How do I know when a subscription renews?
Your bot receives successful_payment again with is_recurring true and a new subscription_expiration_date.
Can my bot cancel a user's subscription?
Yes. editUserStarSubscription stops the next renewal; the user keeps access until the paid period ends.
Sources
At a glance
- 1Create
createInvoiceLink with currency XTR and subscription_period 2592000.
- 2Track
is_recurring, is_first_recurring, subscription_expiration_date.
- 3Manage
editUserStarSubscription to cancel or resume; refundStarPayment to refund.
Updated
