How to Build a Telegram Shop Bot With In-Chat Checkout

A Telegram shop bot shows your products, lets customers build a cart, and then sends a Telegram invoice so they can pay without leaving the chat. Physical goods are paid through a payment provider you connect in @BotFather, with Telegram collecting shipping details if you ask for them; digital goods and services must be paid in Telegram Stars under Telegram's rules. Your bot's job is to confirm each order before money moves and fulfil it afterwards.

This guide walks through the whole build in plain language: planning, the catalogue, the cart, invoices, shipping, the checks before payment, what to do after payment, testing, launching and running the shop. It describes Bot API methods and parameters in words rather than code. For payment details from a developer's angle, our guide to bot payments for developers goes deeper, and Telegram Stars vs TON vs card payments compares the ways to get paid.

Before you start

Decide what you sell

The single biggest decision is whether your products are physical or digital, because the payment rules differ.

• Physical goods and real-world services, such as clothes, food, repairs or event tickets for a physical venue, can be paid with cards and other methods through third-party payment providers Telegram supports. Telegram says it does not process these payments itself; the provider does.
• Digital goods and services, such as e-books, courses, software features, subscriptions or in-bot content, must be paid in Telegram Stars. Telegram's documentation explains this is required to comply with the app stores' rules, and that bots selling digital goods with other currencies or providers may not be shown to mobile users. Our guide to Telegram Stars explains how Stars work for buyers and sellers.

If you sell both, your bot needs both payment paths.

Check what you need legally

A shop on Telegram is still a shop. You may need a business registration, a returns policy, terms of sale, a privacy policy, and to charge and report sales tax or VAT. This is general information, not legal or tax advice; check your local rules or ask a professional. Our guide on Telegram income taxes for creators covers some of the basics.

Choose how you will build

• No-code shop builders for Telegram exist and can be enough for a small catalogue. Check that you create the bot in your own @BotFather account, that you can export orders, and what fees apply. Our guide on building a bot without coding compares this route.
• A developer-built bot gives full control over the flow, data and integrations with your stock and shipping systems.
• A Mini App storefront opens a full shopping interface inside Telegram and hands over to Telegram's checkout. Our guide on building a Telegram Mini App covers the basics.

Prepare the essentials

1. A bot created with @BotFather, with a name, photo and description that make the shop recognisable. See our BotFather guide.
2. Product photos, names, short descriptions, prices and stock levels.
3. Shipping options and prices, if you ship.
4. A payment provider account, for physical goods.
5. A place to store orders: a database, a spreadsheet or your existing shop system.
6. A person who handles orders and customer questions.

How in-chat checkout works

Understanding the sequence makes every later step easier. Here is the flow for a physical product with shipping:

1. The customer chooses products in your bot and taps "Checkout".
2. Your bot sends an invoice: a special message with the title, description, photo, total and a Pay button.
3. The customer taps Pay. Telegram shows a payment form. If you asked for shipping details, Telegram collects the address.
4. Telegram sends your bot a shipping query with the address. Your bot replies with the shipping options available for that address, with prices, or with an error if you cannot deliver there.
5. The customer picks a shipping option and enters payment details in the provider's form.
6. Before charging, Telegram sends your bot a pre-checkout query. Your bot must confirm or decline it quickly; Telegram's documentation says within ten seconds.
7. If your bot confirms, the payment is processed. Your bot receives a successful payment message in the chat, with the details of what was paid.
8. Your bot records the order and starts fulfilment.

For a digital product paid in Stars, the flow is the same without shipping, and the invoice uses Telegram Stars as its currency with no external provider.

Step 1: Connect a payment provider (physical goods)

1. Open @BotFather, choose your bot and find its payments settings.
2. Choose a payment provider from the list Telegram supports in your region. Availability depends on the provider and your country.
3. Follow the provider's connection flow. You may need to complete their business verification.
4. BotFather gives you a provider token for that connection. Your bot includes it when it creates an invoice. Treat it like a password.
5. Many providers also offer a test connection that gives a separate test token, so you can run practice payments without real money. Use it until everything works.

For digital goods paid in Stars, you do not connect a provider. Invoices are created with Stars as the currency and an empty provider token.

How to compare payment providers

If several providers are available to you, compare them on what affects the business, not on brand familiarity:

• Countries and currencies they support for you as a merchant and for your customers.
• Fees per transaction and any monthly charges, from the provider's own pricing page.
• Payment methods your customers use, such as cards or local wallets.
• Payout timing to your bank account.
• Refund and dispute handling, including how you issue refunds and what a dispute costs.
• Verification requirements for your business, which can take days.

Pick one, finish its verification, and keep the test connection for future changes.

Step 2: Build the catalogue

Option A: a catalogue in the chat

For a small range, the bot can show categories as buttons, then products as messages with a photo, a short description, the price and buttons such as "Add to cart" and "Next". This works well for up to a few dozen products.

Tips for chat catalogues:

• Keep descriptions short; link to a page for full details.
• Use inline buttons under the product message and edit the same message when the customer browses, instead of sending a new message each time. The chat stays tidy.
• Show the price and whether it includes tax and shipping.
• Show "out of stock" clearly rather than hiding products customers might search for.

Option B: a Mini App storefront

For larger catalogues, filters, search and rich product pages, a Mini App is easier to use. It opens like a web page inside Telegram, styled to match the user's theme. When the customer is ready to pay, the Mini App can open a Telegram invoice created by your bot through an invoice link, so the payment still runs through Telegram's checkout.

Option C: inline mode for sharing

Inline mode lets users type your bot's username in any chat and pick a product to share. It is a nice extra for products people recommend to friends, not a replacement for the catalogue. Our guide to inline bots explains it.

Keep the catalogue in one place

If you also sell on a website or marketplace, read products and stock from the same source. Two separate lists will drift apart, and you will sell items you do not have.

Step 3: Build the cart

A cart remembers what the customer picked before checkout.

1. Store the cart per user, keyed by their Telegram user ID, in your database.
2. Show a cart summary on request: items, quantities, subtotal, and buttons to change quantity or remove.
3. Check stock again when the customer opens the cart, and tell them if something sold out.
4. Expire old carts after a while, but do not wipe them instantly; people come back.
5. Offer a single "Checkout" button that leads to the invoice.

Small shops sometimes skip the cart and sell one product per invoice. That is simpler and fine for single-product shops. For more than one item per order, a cart is worth building.

Step 4: Create the invoice

When the customer checks out, your bot sends an invoice using the Bot API's invoice method, or creates an invoice link for a Mini App. Key parameters, described in words:

• Title and description: what the customer is buying, in plain words.
• Payload: a private reference your bot will receive back with the payment, such as your internal order ID. The customer does not see it. Keep it to an identifier only; never put the price in it as the source of truth, because your bot should look up the real order.
• Provider token: from BotFather for physical goods; empty for Stars.
• Currency: a three-letter currency code for provider payments, or the code for Telegram Stars for digital goods.
• Prices: a list of labelled amounts, such as each item, tax and discount. Amounts are given in the smallest unit of the currency, for example cents rather than dollars. Getting this wrong by a factor of a hundred is a classic mistake.
• Photo: an optional product image shown on the invoice.
• Need name, phone, email, shipping address: flags asking Telegram to collect these details. Ask only for what you need to deliver.
• Flexible: a flag that tells Telegram the final price depends on the shipping address, so it will send your bot a shipping query.
• Tips: optional suggested tip amounts, if your business accepts tips.

Telegram's documentation lists every invoice parameter and is updated over time, so check it while building.

Write the order before the invoice

Create the order in your database with status "pending payment" before sending the invoice, and put its ID in the payload. Then, whatever arrives later, your bot can check it against a record it wrote itself.

Step 5: Handle shipping queries

If the invoice is flexible, Telegram sends your bot a shipping query once the customer enters an address.

1. Read the country and address fields.
2. Decide which shipping options you offer there, for example standard and express, each with its price.
3. Answer the shipping query with that list, or with an error message such as "Sorry, we do not deliver to this country".

Keep shipping logic simple at first: a few zones with fixed prices. Customers see the options inside the payment form, so labels like "Standard, 3 to 5 working days" help them choose.

Step 6: Answer the pre-checkout query

This is the most important moment in the whole flow. Telegram asks your bot for a final yes or no before the customer is charged.

1. Look up the order using the payload.
2. Check the order still exists and is unpaid.
3. Check the total and currency match exactly what you expect for that order.
4. Check the items are still in stock.
5. Answer yes to proceed, or no with a short, polite error message, such as "Sorry, one item just sold out. Please check your cart."

You must answer quickly; Telegram's documentation gives ten seconds. Keep this check fast and avoid slow outside calls here. Declining at this stage costs the customer nothing, while discovering a problem after payment means a refund.

Step 7: Handle the successful payment

After payment, your bot receives a message in the chat containing the successful payment details: the currency, total, your payload, the shipping option and order info, plus payment charge IDs from Telegram and the provider.

1. Find the order by the payload and mark it paid.
2. Store both charge IDs. You need them for refunds and support questions.
3. Make the update safe to receive twice. Network retries happen. Mark the order as paid only if it is not already paid, so a repeated message does not create a second shipment or a second confirmation.
4. Reduce stock.
5. Send a confirmation with the order number, items, delivery option and what happens next.
6. Notify your team, for example in a private staff group. Our list of chatbot use cases for business includes this kind of internal alert.
7. For digital goods, deliver immediately, such as a download link or unlocked access.

Delivering digital products well

Digital sales paid in Stars need a little more thought on delivery, because the customer expects the product the instant the payment confirms.

• Deliver in the same chat right after the successful payment: a file, a unique link, an access code, or a feature switched on in the bot.
• Make access re-findable. A "My purchases" button that resends links or files saves many support messages from customers who changed phones.
• Protect unique content. Time-limited or per-customer links are harder to pass around than one link everyone shares.
• Consider subscriptions. Telegram has added ways to charge recurring Stars payments for bots and paid channel access. If you sell ongoing access rather than a one-off item, check the current Bot API documentation for subscription options. Our guide to paid Telegram channels covers the channel side.

Step 8: Fulfil, update and support

• Status updates. Message the customer when the order ships, with tracking if available, and when it is delivered. Keep updates to the ones customers find useful.
• Order history. A "My orders" button showing past orders and their status saves support work.
• Support handover. A "Help with my order" button that passes the order number to a person avoids back-and-forth.
• Reviews. After delivery, ask one quick feedback question.

Refunds and returns

Have a clear returns policy and link to it from the bot's menu and the confirmation message.

• Provider payments: refunds for physical goods are made through your payment provider, using the charge ID you stored.
• Stars payments: the Bot API includes a method to refund a Stars payment to the user, using the Telegram payment charge ID. Our guide on Telegram Stars refunds explains the buyer's side.

Record every refund against the order, and tell the customer when it has been issued.

Designing the shopping conversation

Good shop bots feel like a well-organised counter rather than a chat. A few design choices make the difference.

The start message

When someone first opens the bot, show the shop's name, one sentence on what you sell, and three or four buttons: "Browse", "My cart", "My orders", "Help". Do not open with a wall of text or a long list of commands.

A persistent menu

Set the bot's command list in @BotFather so the menu button shows the main actions, such as start, cart, orders and help. Customers who lose their place can always get back.

Back buttons everywhere

Every product, category and cart screen should have a way back. Dead ends are the most common reason customers abandon a chat shop.

Edit, do not spam

When the customer browses or changes a quantity, edit the existing message instead of sending a new one. A chat filled with dozens of product messages is hard to use and easy to mute.

Language and currency

If you serve several countries, the bot can read the language setting of the customer's app and greet them in it. Show prices in the currency you will actually charge, so nothing changes at the payment form.

Discounts, taxes and price lines

The invoice can show several labelled amounts, which lets customers see how the total is made up.

• Discounts: apply coupon codes in your bot before creating the invoice, and show the reduced price and the discount clearly in the cart and invoice description. Check that the final total cannot go below what you intend, and limit codes that can be reused.
• Taxes: if prices exclude tax, show tax as its own line. If they include it, say "including VAT" or the equivalent in the description. Rules differ by country; this is not tax advice.
• Shipping: shown by Telegram from the option the customer picks, so do not add it twice in your own lines.
• Stars invoices are simpler: a single price in Stars for the digital item.

Abandoned checkouts

Some customers open an invoice and never pay. You can see this because the order stays "pending payment".

• Do not chase them repeatedly. One friendly reminder, only if the customer has agreed to receive messages from your shop, is the most that is welcome.
• Release reserved stock after a set time so other customers can buy it.
• Look for patterns. If many customers leave at the same step, such as the shipping options, prices or the form, fix that step.

When to grow beyond a simple bot

Signs that the shop has outgrown a basic chat catalogue:

• The product range no longer fits comfortably into buttons, so customers struggle to find things. Move the catalogue to a Mini App.
• Stock is managed in another system and keeps drifting. Connect the bot to that system as the single source.
• Order volume means staff spend the day copying details. Send orders straight into your order or shipping software.
• Questions outnumber orders. Add a support flow with a human handover, as described in our guide on Telegram customer support for business.

Testing before launch

Test as if you were your most confused customer.

1. Use test payments from your provider's test mode for physical goods.
2. Test every path: one item, several items, changing quantities, removing items, an empty cart.
3. Test shipping: a supported address, an unsupported country, each shipping option.
4. Test the pre-checkout refusal: make an item go out of stock between invoice and payment and check the customer sees a clear message.
5. Test duplicate updates: if your setup allows, replay a successful payment message and confirm only one order is fulfilled.
6. Test on Android, iPhone, desktop and web. Invoices and Mini Apps can look different on each.
7. Test a refund end to end.
8. Check amounts: one wrong decimal is easy to miss and expensive to discover.

For Stars, you will be testing with real Stars unless Telegram's developer test environment fits your setup. Keep test purchases small and refund them.

Launching and getting customers

• Link the bot everywhere: your website, your channel, social profiles, packaging and receipts. Our guide on adding a Telegram chat button covers websites.
• Use your channel for new arrivals, with buttons that open the product in the bot. See running a Telegram channel for an online shop.
• Use start parameters in links, such as one per campaign or per product, so you know which posts bring buyers. Our guide on tracking clicks and sales from Telegram explains the method.
• Announce it to existing customers who already message you on Telegram.

Running the shop day to day

Daily

• Check new orders and that each has been confirmed and shipped.
• Answer support messages.
• Watch for payment errors in your logs.

Weekly

• Review sales, abandoned carts and refunds.
• Update stock and remove discontinued products.
• Read feedback and fix the most common complaint.

Security

• Keep the bot token and provider token secret, and rotate them if they leak.
• Use two-step verification on the account that owns the bot. See our guide on setting up two-step verification.
• Never ask customers for card details or codes in chat. Payments happen only in Telegram's payment form or your provider's page. Add a line saying so to the bot description, because scammers impersonate shops.
• Protect customer addresses and phone numbers; give staff access only to what they need.

Example: a hypothetical tea shop

This is an illustrative scenario, not a real business. A small tea shop builds a bot with a chat catalogue of twenty teas grouped into four categories. Each product message has a photo, a two-line description, the price per pack and "Add to cart". The cart lets customers change quantities. At checkout the bot sends a flexible invoice that asks for name, phone and shipping address; shipping queries return two options for domestic addresses and a polite refusal for countries the shop does not serve. The pre-checkout check confirms stock and the total. After payment, the bot sends an order number and the owner gets an alert in a private group. A separate "Gift card" product, being digital, is sold for Stars. The shop's channel posts new teas with a "Buy in our bot" button, and each button uses a start parameter so the owner can see which posts sell.

Common mistakes

• Selling digital goods through a card provider. Telegram's rules require Stars for digital goods and services in bots.
• Trusting the price in the payload. Always look up the real order and compare totals at pre-checkout.
• Slow pre-checkout answers. Miss the time limit and the payment fails.
• Amounts in the wrong unit. Prices are in the smallest currency unit.
• Fulfilling twice because a payment update arrived twice.
• Asking for data you do not need, such as a phone number for a digital download.
• No returns policy or a policy that differs from your website.
• Letting a contractor own the bot, so you lose the shop if you part ways.

FAQ

Can customers pay by card inside Telegram?

For physical goods and services, yes, through a payment provider connected in @BotFather where one is available for your region. For digital goods and services, Telegram requires payment in Stars.

Does Telegram take a commission on physical sales?

Telegram says it does not process payments for physical goods; your payment provider handles the money and charges its own fees. Check your provider's pricing. Stars payments have their own rules for how sellers receive value; see our guide on withdrawing Telegram Stars.

Do I need a website to run a Telegram shop?

Not technically. The bot can show products and take payment. A website still helps with trust, legal pages and search visibility.

How many products can a shop bot handle?

A chat catalogue works best for a modest range. For large catalogues with filters and search, use a Mini App storefront that hands over to Telegram's checkout.

Can I sell to customers in other countries?

That depends on your payment provider, your shipping options, and the laws on selling abroad. Use shipping queries to offer only destinations you serve.

What if the customer pays but something goes wrong?

Your bot has the charge IDs from the successful payment. Use them to issue a refund through your provider, or through the Bot API for Stars, and tell the customer.

Summary

A Telegram shop bot combines a catalogue, a cart and Telegram's built-in checkout. Physical goods use a payment provider connected in @BotFather; digital goods use Telegram Stars. Write each order before sending the invoice, answer shipping queries with simple zones, check everything quickly at pre-checkout, and treat the successful payment as the start of fulfilment, handled safely even if it arrives twice. Test every path, keep tokens secret, and make returns and support easy to find.