# Telegram Shopping

> LNbits extension that turns a Telegram bot into a Lightning-powered storefront. Products from Inventory, payments via Lightning, management via REST API. Includes a Telegram Mini App and marketing campaign engine.

Customers browse, fill a cart, and pay Lightning invoices through an embedded Mini App inside Telegram. Products are shareable via deep links and inline mode. Shop owners manage orders, fulfillment, messaging, returns, and marketing campaigns through LNbits or the API.

## Core Capabilities

- Telegram Mini App: embedded web storefront with product grid, persistent cart, full checkout
- Deep links and inline mode for product sharing across Telegram chats
- Lightning payments with fiat conversion and store credit
- Order fulfillment tracking: preparing → shipping → delivered
- Return and refund system with Lightning or store credit
- Customer messaging, bidirectional, threaded by customer and order
- Inventory sync with automatic stock deduction
- Marketing campaigns: abandoned cart, back-in-stock, post-purchase, promotion broadcasts
- Customer tracking with activity timestamps
- Shop statistics and analytics

## Quick Start

- [Agent Integration Guide](/ai/agent-readme): Full API reference for AI agents, including end-to-end store setup
- [Integration Prompt](/ai/integration-prompt): Copy-paste system prompt, Python client, and cURL examples for AI assistants
- [Getting Started](/guide/getting-started): Human setup guide

## Authentication

- LNbits wallet keys via `X-API-KEY` header
- Admin key: full access — create, update, approve, send, broadcast
- Invoice key: read access — list orders, messages, returns, stats, customers

## API Endpoints

### Shop Management
- POST /shop — create shop
- GET /shop — list shops
- GET /shop/{id} — get shop
- PUT /shop/{id} — update shop
- DELETE /shop/{id} — delete shop
- POST /shop/{id}/start — enable and start bot
- POST /shop/{id}/stop — disable bot
- POST /shop/{id}/refresh — force product refresh
- POST /shop/test-token — validate bot token

### Orders
- GET /order — list orders (filter by status, limit, offset)
- GET /order/{id} — get order
- PUT /order/{id}/fulfillment — update fulfillment status

### Messages
- GET /message — list messages (supports unread_only filter)
- GET /message/thread — get conversation thread (supports order_id filter)
- GET /message/unread-count — unread count
- POST /message/{shop_id} — send message
- PUT /message/{id}/read — mark as read

### Returns
- GET /return — list returns (filter by status, limit, offset)
- GET /return/{id} — get return
- PUT /return/{id}/approve — approve with refund method
- PUT /return/{id}/deny — deny with note

### Marketing Campaigns
- GET /commercial — list campaigns
- POST /commercial — create campaign
- PUT /commercial/{id} — update campaign
- DELETE /commercial/{id} — delete campaign
- POST /commercial/{id}/broadcast — send to all customers
- GET /commercial/{id}/log — view send log

### Analytics & Utility
- GET /stats — aggregated statistics (uses wallet key, no shop_id needed)
- GET /customer — list customers
- GET /sources/inventory — fetch Inventory extension data
- GET /image/{image_id} — proxy cached product image

## End-to-End Store Setup (for AI agents)

1. POST /shop/test-token — validate bot token
2. GET /sources/inventory — find Inventory ID
3. POST /shop — create shop with settings
4. POST /shop/{id}/start — start bot
5. GET /commercial — review default campaigns
6. PUT /commercial/{id} — customize and enable campaigns
7. Monitor: GET /stats, GET /message/unread-count, GET /order, GET /return

## Pricing

- Free, open source, MIT license
- Self-hosted LNbits extension
- No platform fees

## Links

- GitHub: https://github.com/DoktorShift/telegramshop
- LNbits: https://lnbits.com