API reference

HCann POS backend endpoints. URLs are public; most routes require auth. Base URL: https://pos1.hcann.com

Authentication

POS tablet: POST /api/auth/login with PIN → use Authorization: Bearer <token>
Admin panel: POST /api/admin/login sets pos_token cookie (or use Bearer token)
Public: health, public menu, and checkout only

Health

Method	Path	Auth	Description
GET	`/api/health`	None	Service health check.

Auth

Method	Path	Auth	Description
POST	`/api/auth/login` Body: `{ "pin": "1234" }`	None	POS tablet PIN login. Returns JWT.
GET	`/api/auth/me`	POS (Bearer token)	Current logged-in user.
POST	`/api/admin/login` Body: `{ "email": "you@example.com", "pin": "your-password" }`	None	Admin panel login. Sets pos_token cookie.
GET	`/api/admin/login`	Admin (cookie or Bearer)	Current admin session.
DELETE	`/api/admin/login`	Admin (cookie or Bearer)	Log out of admin panel.

POS — items

Used by the React Native tablet after PIN login.

Method	Path	Auth	Description
GET	`/api/config`	POS (Bearer token)	Merchant config (tax rate, register, Stripe readiness).
GET	`/api/categories`	POS (Bearer token)	Category names for POS filters.
GET	`/api/products` Query: `?category=Appetizers&search=wings`	POS (Bearer token)	Active items for the POS menu.
GET	`/api/products/{id}`	POS (Bearer token)	Single product by ID.

POS — orders

Method	Path	Auth	Description
GET	`/api/orders` Query: `?limit=50&offset=0&search=ORD-2026&status=pending\|completed\|failed\|refunded`	POS (Bearer token)	List and search order history.
POST	`/api/orders` Body: `{ "lineItems": [{ "productId": "20", "quantity": 2 }], "discountCents": 0, "paymentMethod": "card", "paymentStatus": "pending", "tabLabel": "Table 5", "idempotencyKey": "<uuid>" }` Inventory deducts only when paymentStatus is completed.	POS (Bearer token)	Create order. Use paymentStatus pending for open tabs.
GET	`/api/orders/{id}` Example id: ORD-20260906-0003	POS (Bearer token)	Retrieve any order by UUID or receipt number.
PATCH	`/api/orders/{id}` Body: `{ "lineItems": [{ "productId": "20", "quantity": 3 }], "discountCents": 0, "tabLabel": "Table 5" }` Accepts UUID or receipt number. Omitted fields keep their current value. 404 if missing, 409 if already paid.	POS (Bearer token)	Update a pending open tab (lines, discount, tabLabel).
DELETE	`/api/orders/{id}` Returns 409 when the order is already paid.	POS (Bearer token)	Delete a pending open tab. Completed orders cannot be deleted.
POST	`/api/orders/{id}/complete` Body: `{ "paymentMethod": "cash\|card\|online", "cashReceivedCents": 5000, "lineItems": [...], "discountCents": 0, "stripePaymentIntentId": "..." }` Accepts UUID or receipt number. Omit lineItems/discountCents to pay the tab as it stands.	POS (Bearer token)	Complete and pay a pending tab. Deducts inventory.

POS — reports

Method	Path	Auth	Description
GET	`/api/reports/best-sellers` Query: `?days=30&limit=20`	POS (Bearer token)	Best-selling products from completed orders.

Stripe

Method	Path	Auth	Description
POST	`/api/stripe/connection-token`	POS (Bearer token)	Stripe Terminal connection token for the connected account.
POST	`/api/stripe/payment-intent` Body: `{ "amountCents": 1500, "orderId": "...", "idempotencyKey": "<uuid>" }`	POS (Bearer token)	Create a PaymentIntent for in-person card payment.
POST	`/api/stripe/webhook`	Stripe signature	Stripe webhook handler (checkout, payments, Connect).

Public menu

No auth — customer-facing online ordering.

Method	Path	Auth	Description
GET	`/api/public/menu/{slug}`	None	Public menu JSON for /menu/{slug}.
POST	`/api/public/checkout/{slug}` Body: `{ "lineItems": [{ "productId": "1", "quantity": 1 }] }` If customer_token cookie is set, order is linked to that account.	None	Create Stripe Checkout session for online order.
POST	`/api/public/auth/{slug}/register` Body: `{ "email": "you@example.com", "name": "Jane", "password": "...", "turnstileToken": "..." }` Sends a verification email. Customer must verify before sign-in. turnstileToken required when TURNSTILE_SECRET_KEY is set.	None	Create a customer account and send a verification email.
GET	`/api/public/auth/{slug}/verify-email` Query: ?token=... Redirects to /menu/{slug}?verified=1 or ?verified=error.	None	Email verification link from customer inbox.
POST	`/api/public/auth/{slug}/resend-verification` Body: `{ "email": "you@example.com", "turnstileToken": "..." }`	None	Resend customer verification email.
POST	`/api/public/auth/{slug}/login` Body: `{ "email": "you@example.com", "password": "...", "turnstileToken": "..." }` Requires verified email. turnstileToken required when TURNSTILE_SECRET_KEY is set.	None	Customer sign-in. Sets customer_token cookie.
GET	`/api/public/auth/{slug}/me`	None	Current customer session (customer_token cookie).
DELETE	`/api/public/auth/{slug}/logout`	None	Clear customer session cookie.
GET	`/api/public/orders/{slug}` Requires customer_token cookie.	None	Completed order history for signed-in customer.
GET	`/api/public/orders/{slug}/{id}`	None	Single order for signed-in customer (UUID or order number).

Admin

Admin panel CRUD. Auth via pos_token cookie or Bearer JWT with ADMIN/MANAGER role.

Method	Path	Auth	Description
GET	`/api/admin/settings`	Admin (cookie or Bearer)	Merchant settings.
PATCH	`/api/admin/settings`	Admin (cookie or Bearer)	Update merchant settings.
GET	`/api/admin/products` Query: `?search=wings&sort=name\|category\|price\|stock\|sku`	Admin (cookie or Bearer)	List products (search, sort, pagination).
POST	`/api/admin/products`	Admin (cookie or Bearer)	Create product.
PATCH	`/api/admin/products/{id}`	Admin (cookie or Bearer)	Update product.
DELETE	`/api/admin/products/{id}`	Admin (cookie or Bearer)	Delete product.
GET	`/api/admin/categories`	Admin (cookie or Bearer)	List categories.
POST	`/api/admin/categories`	Admin (cookie or Bearer)	Create category.
PATCH	`/api/admin/categories` Body: `{ "orderedIds": ["id1", "id2"] }`	Admin (cookie or Bearer)	Reorder categories.
PATCH	`/api/admin/categories/{id}`	Admin (cookie or Bearer)	Update category.
DELETE	`/api/admin/categories/{id}`	Admin (cookie or Bearer)	Delete category.
GET	`/api/admin/staff`	Admin (cookie or Bearer)	List staff users.
POST	`/api/admin/staff`	Admin (cookie or Bearer)	Create staff user with PIN.
PATCH	`/api/admin/staff/{id}`	Admin (cookie or Bearer)	Update staff user.
GET	`/api/admin/stripe/connect`	Admin (cookie or Bearer)	Stripe Connect account status.
POST	`/api/admin/stripe/connect`	Admin (cookie or Bearer)	Create Connect account or onboarding link.
POST	`/api/admin/upload`	Admin (cookie or Bearer)	Upload product image (multipart form).
GET	`/api/admin/orders` Query: `?limit=25&offset=0&search=Table 5&status=pending\|completed\|failed\|refunded`	Admin (cookie or Bearer)	Order history with search and pagination.
GET	`/api/admin/orders/{id}`	Admin (cookie or Bearer)	Single order by UUID or receipt number.
DELETE	`/api/admin/orders/{id}`	Admin (cookie or Bearer)	Delete a pending open tab.
GET	`/api/admin/reports/best-sellers` Query: `?days=30&limit=20`	Admin (cookie or Bearer)	Best sellers report for admin UI.