Shop Bot / Guide

Run a Telegram store with Shop Bot.

Customers shop entirely inside the store's bot: browse, pay in Telegram Stars, and get their files at once. The store's admins run the catalog, payments, and support from the same bot. This guide walks through both, and lists every command and menu.

Start the tutorial See every command

At a glance

Where you use it: Inside the merchant's own Telegram store bot. Customers and admins use the same bot; admin commands answer only the store's admins.
Customer path: Find a product, pay in Stars, get your files, and ask for help.
Admin path: Stock the catalog, deliver keys, handle refunds and payments, promote, and read reports.
Shop Bot today: BuiltNot publicly hosted

Tutorial

Operate it step by step.

Follow every step, or only the customer or admin path. Your progress stays in this browser.

Step 1 of 16 · Customer and Admin

Open the store

Start the store bot and find your way around its home menu.

Do this

/start: Opens the home menu. A link someone shared can open a product, a category, or a gift directly.
/help: Shows the same menu with a short explanation.

Illustrative example

You: /start
Bot: Welcome to Example Store. [Browse] [Search] [Cart] [Orders] [My Files] [Support]

You should see. The home menu with Browse, Search, Wishlist, Cart, Orders, Custom Orders, My Files, Referrals, and Support. Membership appears when the store has a plan, and Admin only for the store's admins.

Tip. Telegram's command menu (the / button) lists the customer commands in your language.

Step 2 of 16 · Customer

Find a product and pay in Stars

Add products to the cart, apply a coupon, and pay with Telegram Stars.

Do this

Browse → category → product: Opens a product. Choose a variant if it has several.
Add to Cart: Adds it. Search finds products by name instead.
Cart → Add coupon: Applies one coupon code; /coupon <code> does the same.
Checkout → Pay: Creates a Stars invoice; Telegram's Pay button completes it.

Illustrative example

You: Cart → Checkout
Bot: Invoice: Example icon set ×1 [Pay ⭐]
Bot: Payment received. Your files are ready in My Files.

You should see. A paid order, and the files or keys it unlocks delivered in the chat right away.

Tip. Checkout reserves limited stock, such as licence keys, while you pay.

Step 3 of 16 · Customer

Get your files and keys

Download what you bought, now or later, and review it.

Do this

My Files: Every file you can download, with downloads used and allowed.
Orders → order → View Files: The files from one order.
Orders → order → Write review: Rate the purchase from 1 to 5 stars and add text if you like.

You should see. The file sent privately in the chat. Keys arrive as text, or as a text file when there are many.

Tip. Downloads can be limited in number and time by the store. If you run out, ask Support; the store can restore them.

Step 4 of 16 · Customer

Send a product as a gift

Pay for a file product on someone else's behalf.

Do this

Product → Buy as a gift: Pays for a separate gift order.
Orders → order → Get gift link: Shows the link to send. Whoever opens it first receives the files.

You should see. A gift link; once it is redeemed, the files belong to the recipient.

Step 5 of 16 · Customer

Join a membership

Subscribe to the store's monthly plan and use members' items.

Do this

/membership: Shows the plan and your access.
Join → Pay: Starts a 30-day subscription paid in Stars through Telegram.
Members' items → Get: Delivers a members-only file while your membership is live.
Cancel renewal: Stops the next renewal; your access lasts until the period ends. Resume renewal restarts it.

You should see. Live membership with access to the members' category until the period ends.

Step 6 of 16 · Customer

Get help with an order or payment

Ask the store for help and follow the conversation.

Do this

/newticket or Support → New ticket: Describe the problem; link a recent paid order if it is about one.
/mytickets: Open a request to read replies, or send one more message while it is open.
/paysupport: The payment policy, your recent orders, and a payment-support request.

You should see. A numbered request. The store's reply arrives in the chat and stays in My tickets.

Step 7 of 16 · Customer and Admin

Request custom work

Send the store a brief for work that is not in the catalog, answer its quote, and handle the request as an admin.

Do this

/customorder or Custom Orders: Answer the prompts for the brief; budget, deadline, and notes are optional. Confirm sends it. Once you have requests, Custom Orders lists them, with New request.
Admin → Custom Orders Queue → request: Admins read the brief, then Approve, Reject with a reason, Clarify with a question, or Force Cancel. An approved request gets Create Quote, and a paid one Mark Fulfilled.
Open request → Accept quote: The store messages you when it answers, quotes, or asks a question. Accept quote sends a Stars invoice, Decline quote turns the quote down, and Reply to clarification answers the question.
/cordqueue, /cordstatus: Admins list pending requests and count them by status.

You should see. The request in the store's queue, each decision sent to the customer, and an accepted quote billed as a Stars invoice.

Step 8 of 16 · Customer

Language, news, and referrals

Set the store up the way you like it.

Do this

/language: Pick one of the store's languages, or Automatic to follow Telegram.
/news: Turn the store's news on or off. Every news message also has Unsubscribe.
/referral: Your referral link, who joined through it, and your credit; /credit shows the balance.

You should see. Your preferences, kept by the store bot.

Step 9 of 16 · Admin

Open the admin menu

Find the store's administration, which only its admins can see.

Do this

/start → Admin: The Admin button appears on the home menu for the store's admins.
/adminlist: A quick summary of categories, products, and coupons.

You should see. The admin menu: Categories, Items, Coupons, Orders, Reviews, Referrals, Custom Orders Queue, Invoices.

Tip. Every admin has the same rights. The store's admin list is set when the store is deployed, not in the bot.

Step 10 of 16 · Admin

Add a product and its file

Create a category and a product, attach its file, and publish it.

Do this

/addcat <title>: Creates a category.
/additem <category_id> <price> <title>: Creates a hidden product, priced in Stars.
/upload <item_id>: Send it with the file, or reply to the file. Variants use v<variant_id>.
/toggleitem <item_id>: Publishes the product.
/pushupdate <item_id>: Later: previews, then with CONFIRM sends a new version to past buyers.

Illustrative example

You: /additem 4 <price> Example icon set
Bot: Created item #12 (hidden). Upload its file with /upload 12.

You should see. A published product customers can find under Browse.

Step 11 of 16 · Admin

Sell licence keys

Load keys for a product and keep stock healthy.

Do this

/addkeys <item_id>: Paste keys, one per line, or send a text file.
/stock <item_id>: Shows keys available, held, and sold.
/voidkeys <item_id>: Previews, then with CONFIRM withdraws unsold keys.

You should see. Each paid order receives its own key.

Tip. /stock <item_id> release frees keys held by checkouts that were never paid.

Step 12 of 16 · Admin

Handle orders, refunds, and support

Look into an order, refund it, restore downloads, and answer support.

Do this

/order <order_id>: Payment and delivery state for one order.
/refund <order_id>: Shows what would happen; add CONFIRM to refund in Stars.
/regrant <order_id>: Restores downloads for an order.
/tickets, /ticket <id>, /reply <id> <text>, /closeticket <id>: Work the support queue.
/invoice: Bills a customer for something outside the catalog.

You should see. The customer is refunded or helped, and every action is recorded.

Step 13 of 16 · Admin

Resolve a payment that needs a decision

Deal with Stars receipts that could not be matched to an order automatically.

Do this

/payments: Open receipts.
/payment <receipt_id>: What was paid and why it is open.
/payretry <receipt_id>: Lets the reconciler try again.
/payresolve <receipt_id> [KEPT] <note>: Records how you handled it by hand.
/payrefund <receipt_id>: Previews, then with CONFIRM returns the Stars.

You should see. No receipt left open without a recorded outcome.

Step 14 of 16 · Admin

Promote the store

Use coupons, news broadcasts, links, and referrals.

Do this

Admin → Coupons → New Coupon: Code, percentage, limits, and expiry; /setcoupon is the short form.
/broadcast: Reply to a message with it to preview a news broadcast, then /broadcast send <id>.
/link <item_id>: A link that opens a product; /link cat <id> opens a category.
/referralstats: How referrals are doing.

You should see. Broadcasts reach only customers who turned news on.

Step 15 of 16 · Admin

Offer a membership

Sell a monthly plan that unlocks a members' category.

Do this

/plan_new <category_id> <price> <title>: Creates the plan for a category.
/plans: Plans, members, and the last 30 days' charges.
/plan_price <id> <price>: Changes the price for new members; current members keep theirs.
/plan_off <id>: Stops new joins; /plan_on resumes them.

You should see. Customers see Membership on the home menu.

Step 16 of 16 · Admin

Read reports and handle data requests

See how the store is doing and honor a customer's data request.

Do this

/dashboard 30: Performance over 7, 30, or 90 days.
/sales 7: Sales and support for the last days.
/export 30: Paid and refunded orders as a CSV file.
/forget <user_id>: Previews, then with CONFIRM deletes a customer's data except payment records.

You should see. Reports in the chat, and a recorded deletion when a customer asks.

Command tree

Every command and menu, expanded.

Typed commands, menus, and the buttons inside them, with who can use each. A step link opens the part of the tutorial that walks through it.

Customer commands

Typed in the store bot. Telegram's command menu lists most of them, in the customer's language.

/startCommandCustomer
Opens the store's home menu, or a shared product, category, gift, or referral link. Step 1
/helpCommandCustomer
Shows help and the home menu. Step 1
/coupon <code>CommandCustomer
Applies a coupon to the cart; /coupon off removes it. Step 2
/membershipCommandCustomerNeeds a membership plan
Opens the store's membership plans and your access. Step 5
/newticketCommandCustomer
Starts a support request. Step 6
/myticketsCommandCustomer
Lists your support requests and their replies. Step 6
/paysupportCommandCustomer
Shows the payment policy and your recent orders, with a payment-support request. Step 6
/customorderCommandCustomer
Starts a new request for custom work. Step 7
/referralCommandCustomer
Shows your referral link, referrals, and credit; /referrals does the same. Step 8
/creditCommandCustomer
Shows your referral credit balance. Step 8
/newsCommandCustomer
Turns the store's news messages on or off. Step 8
/languageCommandCustomerNeeds more than one store language
Chooses the store's language, or follows Telegram's. Step 8
/termsCommandCustomer
Shows the store's terms.
/privacyCommandCustomer
Shows the store's privacy notice.
/cancelCommandCustomer
Stops whatever the bot is asking you to type.

Customer menus

Buttons under the bot's messages. Paging, Back, and Home buttons are not listed.

Home menuMenuCustomer
The store's main menu, from /start or /help. Step 1
- BrowseButtonCustomer
  Categories, then products. Step 2
  - ProductScreenCustomer
    A product's details and actions. Step 2
    - PreviewButtonCustomer
      Sends the product photo.
    - Add to CartButtonCustomer
      Adds the product, or a chosen variant, to the cart. Step 2
    - Buy as a giftButtonCustomer
      Pays for a file product as a gift with its own link. Step 4
    - WishlistButtonCustomer
      Saves or removes the product.
    - See reviewsButtonCustomer
      Opens published reviews.
    - ShareButtonCustomer
      Builds a link to the product and opens Telegram's share sheet.
- SearchButtonCustomer
  Finds products by name. Step 2
- WishlistButtonCustomer
  Your saved products.
- CartButtonCustomer
  Quantities, coupon, and checkout. Step 2
  - Minus / Plus / RemoveButtonCustomer
    Changes a line's quantity or removes it.
  - Add coupon / Remove couponButtonCustomer
    Applies or removes one coupon code. Step 2
  - CheckoutButtonCustomer
    Creates a Telegram Stars invoice for the cart. Step 2
    - PayButtonCustomer
      Telegram's own payment button; you pay in Stars. Step 2
- OrdersButtonCustomer
  Your order history. Step 3
  - OrderScreenCustomer
    One order's state and what it unlocked. Step 3
    - View FilesButtonCustomer
      Opens the files the order paid for. Step 3
    - Get gift linkButtonCustomer
      Shows the link for a gift that is not redeemed yet. Step 4
    - Write reviewButtonCustomer
      Rates the purchase from 1 to 5 stars, with optional text. Step 3
    - Download all keysButtonCustomer
      Sends the order's licence keys as a text file when they are too long for a message.
- Custom OrdersButtonCustomer
  Lists your custom requests, or starts the first one. Step 7
  - New requestButtonCustomer
    Starts a new request for custom work. Step 7
  - RequestScreenCustomer
    One request's status and the actions it allows. Step 7
    - Accept quoteButtonCustomer
      Accepts the store's quote and sends a Telegram Stars invoice for it. Step 7
    - Decline quoteButtonCustomer
      Declines the quote. Step 7
    - Reply to clarificationButtonCustomer
      Answers the store's question about the request. Step 7
    - My requestsButtonCustomer
      Returns to your list of requests.
- My FilesButtonCustomer
  Every file you can download, with downloads used and allowed. Step 3
- MembershipButtonCustomerNeeds a membership plan
  Plan summary, Join, members' items, and renewal. Step 5
  - JoinButtonCustomer
    Creates a 30-day recurring Stars invoice. Step 5
  - Members' itemsButtonCustomer
    Members-only products; Get delivers one to a member. Step 5
  - Cancel renewal / Resume renewalButtonCustomer
    Stops or restarts the Telegram subscription renewal. Step 5
- ReferralsButtonCustomer
  Your link, referral counts, and credit. Step 8
- SupportButtonCustomer
  New ticket and My tickets. Step 6
  - New ticketButtonCustomer
    Starts a request, optionally linked to a recent paid order. Step 6
  - My ticketsButtonCustomer
    Your requests; open one to read replies or reply once more. Step 6
- Want a shop like this?ButtonCustomerNeeds the store's promotion setting
  Opens ApexAi's Shop Bot page.
- AdminButtonAdmin
  Opens the merchant's admin menu; shown only to the store's admins. Step 9
News messageScreenCustomer
A store broadcast you opted into, with Unsubscribe. Step 8
Invoice messageScreenCustomer
A one-off invoice from the store: View Invoice, then Pay. Step 6
Custom request updateScreenCustomer
Tells you when the store approves, rejects, quotes, fulfills, cancels, or reopens your request, asks about it, or a quote expires. Step 7
- Open requestButtonCustomer
  Opens the request when a quote or a question is waiting for you. Step 7
Cart reminderScreenCustomerNeeds the store's cart-reminder setting (off by default)
One reminder about a cart you can still check out: View cart, or Don't remind me. Step 2

Admin menu

Shown only to the store's admins, from the Admin button on the home menu.

Admin menuMenuAdmin
The merchant's menu inside the store bot. Step 9
- CategoriesButtonAdmin
  Categories with their visibility. Step 10
- ItemsButtonAdmin
  Products with their state and price. Step 10
- CouponsButtonAdmin
  Coupon list, detail, Activate or Deactivate, and New Coupon. Step 14
- OrdersButtonAdmin
  The latest twenty orders. Step 12
- ReviewsButtonAdmin
  Pending reviews: Approve, Reject, Hide, Reveal, Respond. Step 12
- ReferralsButtonAdmin
  The newest twenty referral records. Step 14
- Custom Orders QueueButtonAdmin
  Pending requests: Full brief, Approve, Reject, Clarify, Create Quote, Mark Fulfilled, Force Cancel. Step 7
- InvoicesButtonAdmin
  Pending one-off invoices, with Cancel Invoice. Step 12
- Upload FileButtonAdmin
  Shows how to attach files; /upload is the usual way. Step 10

Admin commands

Typed by the store's admins. Every admin has the same rights; the bot checks each command against the store's admin list.

CatalogMenuAdmin
Categories, products, files, and photos. Step 10
- /adminlistCommandAdmin
  Summarizes categories, products, and coupons.
- /addcat <title>CommandAdmin
  Creates a category. Step 10
- /togglecat <category_id>CommandAdmin
  Shows or hides a category.
- /delcat <category_id>CommandAdmin
  Stages a category for deletion; /confirm completes it.
- /additem <category_id> <price> <title>CommandAdmin
  Creates a hidden product, priced in Stars. Step 10
- /upload <item_id> [v<variant_id>]CommandAdmin
  Attaches the file you send or reply to, for a product or variant. Step 10
- /setphoto <item_id>CommandAdmin
  Sets the product's preview photo from the photo you send.
- /settitle, /setdesc, /setprice <item_id> …CommandAdmin
  Changes a product's title, description, or price.
- /setversion <item_id> <label|->CommandAdmin
  Sets or clears a product's version label.
- /pushupdate <item_id> [v<variant_id>] [CONFIRM]CommandAdmin
  Previews, then sends a new file version to past buyers. Step 10
- /toggleitem <item_id>CommandAdmin
  Publishes or hides a product. Step 10
- /delitem <item_id>CommandAdmin
  Stages a product for deletion or archiving; /confirm completes it.
- /confirmCommandAdmin
  Confirms the deletion you staged.
- /link <item_id> or /link cat <category_id>CommandAdmin
  Builds a link that opens a product or category. Step 14
- /setslug, /clearslug <item_id>CommandAdmin
  Sets or clears a product's external slug.
Variants and bundlesMenuAdmin
Priced variants of a product, and bundles of file products. Step 10
- /variants <item_id>CommandAdmin
  Lists a product's variants.
- /variant_add <item_id> <price> <label>CommandAdmin
  Adds a variant. Step 10
- /variant_price, /variant_label, /variant_note <variant_id> …CommandAdmin
  Changes a variant's price, label, or licence note.
- /variant_off, /variant_on <variant_id>CommandAdmin
  Stops or resumes a variant's sales.
- /bundle_new <category_id> <price> <title>CommandAdmin
  Creates a hidden bundle.
- /bundle <bundle_id>CommandAdmin
  Shows a bundle's contents and whether it is ready.
- /bundle_add, /bundle_remove <bundle_id> <item_id>CommandAdmin
  Adds or removes a file product.
Licence keysMenuAdmin
Products delivered as keys. Step 11
- /addkeys <item_id>CommandAdmin
  Imports keys from your message or a text file. Step 11
- /stock [item_id]CommandAdmin
  Reports key inventory; /stock <item_id> release frees holds from unpaid checkouts. Step 11
- /voidkeys <item_id> [CONFIRM]CommandAdmin
  Previews, then withdraws unsold keys. Step 11
Orders, refunds, and supportMenuAdmin
After the sale. Step 12
- /order <order_id>CommandAdmin
  Shows an order's payment and delivery state. Step 12
- /refund <order_id> [CONFIRM] [reason]CommandAdmin
  Previews, then refunds a paid order in Stars. Step 12
- /regrant <order_id> [downloads]CommandAdmin
  Restores downloads for an order. Step 12
- /tickets [open|all] [page]CommandAdmin
  Lists the support queue. Step 12
- /ticket <ticket_id>CommandAdmin
  Shows a request and its latest messages. Step 12
- /reply <ticket_id> <text>CommandAdmin
  Replies to the customer. Step 12
- /closeticket <ticket_id>CommandAdmin
  Closes the request and tells the customer. Step 12
- /invoiceCommandAdmin
  Creates a one-off invoice for a customer. Step 12
- /dm <user_id> <message>CommandAdmin
  Sends a customer a recorded direct message.
PaymentsMenuAdmin
Stars receipts that need a decision. Step 13
- /paymentsCommandAdmin
  Lists open receipts. Step 13
- /payment <receipt_id>CommandAdmin
  Inspects one receipt. Step 13
- /payretry <receipt_id>CommandAdmin
  Hands a receipt back to the automatic reconciler. Step 13
- /payresolve <receipt_id> [KEPT] <note>CommandAdmin
  Closes a receipt you handled by hand. Step 13
- /payrefund <receipt_id> [CONFIRM]CommandAdmin
  Previews, then refunds a receipt. Step 13
PromotionMenuAdmin
Coupons, broadcasts, and referrals. Step 14
- /setcoupon <code> <percent> <0|1>CommandAdmin
  Creates or updates a simple percentage coupon. Step 14
- /delcoupon <code>CommandAdmin
  Stages a coupon for deletion or deactivation; /confirm completes it.
- /broadcastCommandAdmin
  Reply to a message with /broadcast to preview it as news; then /broadcast send <id> or cancel <id>. Step 14
- /broadcastsCommandAdmin
  Lists recent broadcasts and their delivery counts.
- /referrallist, /referralstatsCommandAdmin
  Lists referrals and summarizes credit issued.
- /referralvoid <id>, /referralgrant <user_id> <amount>CommandAdmin
  Voids a referral or adjusts a customer's credit.
MembershipsMenuAdminNeeds a members' category
Monthly plans that unlock a members' category. Step 15
- /plansCommandAdmin
  Lists plans, members, and the last 30 days' charges. Step 15
- /plan_new <category_id> <price> <title>CommandAdmin
  Creates a plan for a category. Step 15
- /plan_price <id> <price>CommandAdmin
  Changes the price for new members. Step 15
- /plan_off, /plan_on <id>CommandAdmin
  Stops or resumes new joins. Step 15
Reports and privacyMenuAdmin
How the store is doing, and customer data requests. Step 16
- /sales [days]CommandAdmin
  Sales and support summary. Step 16
- /dashboard [7|30|90]CommandAdmin
  Performance dashboard with 7, 30, and 90-day buttons. Step 16
- /export [days]CommandAdmin
  Paid and refunded orders as CSV. Step 16
- /customer <telegram_user_id>CommandAdmin
  A customer's history with the store. Step 16
- /forget <user_id> [CONFIRM]CommandAdmin
  Previews, then deletes a customer's non-payment data. Step 16
- /cordqueue, /cordstatusCommandAdmin
  Pending custom requests, and counts by status. Step 7
- /reopencord <request_id>CommandAdmin
  Reopens an expired custom request. Step 7

Not listed: paging, Back, and Home buttons, and the operator tools of whoever runs the store's instance (health, smoke tests, logs, evidence, reconciliation).

Troubleshooting

When something does not work.

Common Shop Bot problems and how to fix them
What you see	What to do
Browsing and checkout are refused	The store is paused by its operator. Purchases you already made, your files, and support still work. Get help with an order or payment
A file will not download any more	The store's download limit for that order is used up or expired. Ask Support; an admin can restore it with /regrant. Get your files and keys
I paid but did not receive my order	Open /paysupport and send a payment-support request with the order. Admins can check it with /order and /payments. Resolve a payment that needs a decision
A coupon is refused	It may be inactive, used up, expired, or not valid for this cart. Check it under Admin → Coupons.
The Admin button does not appear	Your Telegram account is not on the store's admin list. That list is set when the store is deployed, not in the bot. Open the admin menu
A product does not show under Browse	New products start hidden. Publish it with /toggleitem, and check its category is visible with /togglecat. Add a product and its file
Membership does not appear on the home menu	The store has no active plan. Create one with /plan_new or turn one back on with /plan_on. Offer a membership

Back to Shop Bot Discuss Shop Bot