Orders Extension

Telegram Shopping can forward every paid order to the Orders extension, a separate LNbits extension that acts as a unified order ledger across all your sales channels.

TPoS, Telegram Shopping, and any future extension that sells things can all push orders to the same place. One view for everything you've sold.

Why use it

Without Orders, each extension keeps its own records. That's fine for a single shop. But if you run a TPoS at your counter and a Telegram bot online, you're checking two dashboards.

Orders gives you:

• One ledger — all paid orders from all extensions in a single list
• Notifications — Telegram, Nostr, and email alerts when orders come in
• Customer notifications — automatic order-received and order-shipped messages to the buyer
• Public order tracking — a shareable link customers can check without logging in
• Shipping workflow — mark orders as shipped, triggering customer notifications
• Business identity — attach your business name and address to order receipts

Setting it up

1. Install the Orders extension from the LNbits extension manager
2. Enable it for the same user that owns your Telegram Shopping wallet
3. In Telegram Shopping, open your shop settings and turn on Forward orders to Orders extension

That's it. The next paid order will appear in both places.

Orders extension settings

Configure the Orders extension itself for notifications and business info:

Setting	Purpose
Telegram	Your Telegram chat ID for new-order alerts
Nostr npub	Nostr public key for new-order alerts
Email	Email address for new-order alerts
Fiat denomination	Default fiat currency for display
Business name	Shown on public order pages
Business address	Shown on public order pages
Order received message	Custom text sent to the customer when an order is created
Order shipped message	Custom text sent to the customer when you mark an order as shipped

What gets forwarded

When a customer pays, Telegram Shopping sends the full order to the Orders extension via an internal API call. The forwarded data includes:

Field	Source
Source	telegramshop
Payment hash	From the Lightning payment
Amount (msat)	Total in millisatoshis
Memo	Payment description
Currency	Fiat currency code (if applicable)
Fiat amount	Original price in fiat (if applicable)
Exchange rate	Sats-to-fiat rate at time of payment
Line items	Each product's title, quantity, price, SKU, and weight
Buyer email	Validated; invalid emails are silently dropped
Buyer address	Shipping address from checkout
Timestamps	Original order creation time

The forwarding is fire-and-forget. If the Orders extension is unreachable or throws an error, the Telegram Shopping order still completes normally. Nothing blocks the customer experience.

Fulfillment sync

When you move an order to Shipping (stage 2) in Telegram Shopping, the fulfillment status is automatically updated to Shipped in the Orders extension. This keeps both systems in sync without manual work.

The sync happens alongside the customer notification — when you advance an order to "Shipping" in Telegram Shopping, two things happen at once:

1. The customer gets notified in Telegram (with any tracking note you added)
2. The Orders extension record updates to "Shipped", triggering its own configured notifications (email, Nostr, Telegram alerts)

No extra configuration needed. If forward_to_orders is enabled, the fulfillment sync is automatic.

How it works

The integration uses LNbits' internal cross-extension API pattern:

1. Customer pays → Telegram Shopping processes the order as usual (stock deduction, confirmations, notifications)
2. Telegram Shopping checks: is forward_to_orders enabled for this shop?
3. Checks: does this user have the Orders extension active?
4. If both pass, it POSTs the order data to /orders/api/v1/orders using an internal bearer token
5. Orders extension stores the record, sends notifications, and makes it available in its dashboard

Steps 2–5 happen in the background. The customer sees their confirmation immediately.

Fiat and sats

If your shop uses a fiat currency (EUR, USD, etc.), the forwarded order includes both the sat amount and the fiat amount with the exchange rate at the time of payment. The Orders extension stores all three, so you can view orders in either denomination.

If your shop prices in sats, only the sat amount is sent. The currency fields are left empty.

Requirements

• Orders extension installed and enabled for the same LNbits user
• Telegram Shopping with forward_to_orders toggled on in shop settings
• Both extensions on the same LNbits instance (cross-extension calls are internal)