ShopDesk — Admin Panel

Dashboard overview

Cross-cutting KPIs (orders, revenue, customers, stock, commission, etc.), admin wallets, and distance from the configured store location (miles, km, meters).

Documentation

Full guide with sections, permissions, APIs, and figures — readable in the browser or as Markdown.

Open documentation Legacy .md

Wallet, adjust & geo APIs

Wallet: GET /api/admin/wallet/me, GET /api/admin/wallet/me/transactions (ledger; use GET /api/admin/wallet/:userId/transactions for another staff id with wallet.read or Super Admin).

Adjust: POST /api/admin/wallet/adjust (Super Admin) — writes balance and a ledger row.

Geo: public GET /api/geo/store; distance GET /api/geo/distance?lat=&lng= or POST /api/geo/distance with JSON lat & lng (or latitude / longitude). Store origin: GET /api/admin/store-geo (platform.read), PUT /api/admin/store-geo (shop_profile_editor: Super Admin or Operations Admin).

Admin management

Create internal administrators and manage status. Super Admin only for create / delete / reset password. Commerce extras: open Sections on a staff row, tick Vendor management, Shop profile, Product management, Stock, Catalog & payments, Orders, Financial, Tax, Notifications, or Communications (Deskia), then Save section access. That merges with their adminRole (e.g. Operations Admin). Revoke: uncheck all and Save, or click Clear all extras — both store an empty permissionOverrides list. The affected admin should sign out and sign in again to refresh the sidebar and APIs.

Create admin

Email Password Full name Phone Username Department Role

Optional Commerce section grants

Same keys as Sections on an existing staff row. Leave closed for role-only access.

All admin accounts

Roles & permissions

Roles are enforced on every admin API. Super Admins assign roles from Admin management (dropdown per user) or below. Business TIN for vendors is collected under Vendor / Compliance.

Your permission patterns

—

Test a permission

Checks your current JWT role against one key (same logic as the API gateway).

Permission key

Role definitions

Permission glossary

Every defined permission key and its meaning (includes keys used by roles and by the API matrix).

Live data from GET /api/admin/roles. Static snapshot: /permission-glossary.json — run npm run catalog:permission-glossary after changing lib/platformRoles.js.

Admin API reference

Live table: Method, Path, RBAC, Summary — same rows as adminApiEndpoints on GET /api/catalog.

Static mirror: /admin-api-rbac.json (same adminApiEndpoints + rbacLegend; regenerate after route changes).

RBAC column, data sources & regenerate admin-api-rbac.json

The RBAC column shows rbac · rbacLabel (slug · label) for each row — the same fields as in adminApiEndpoints. Special rbac values are documented in rbacLegend on GET /api/catalog and in /admin-api-rbac.json:

jwt — JWT (any signed-in user)
any_admin — Admin JWT (role=admin; no permission key)
super_admin — Super Admin only (adminRole=super_admin)
Any other value — permission key, enforced with the same rules as the gateway (label often matches the slug)

If adminApiEndpoints is missing or empty from GET /api/admin/roles, the matrix is loaded from GET /api/catalog, then from /admin-api-rbac.json.

Regenerate the static file when routes change:

npm run catalog:admin-api-rbac

Same as the one-liner in lib/apiCatalog.js (file header) that writes public/admin-api-rbac.json.

Compliance center

Vendor KYC, tax flags, and compliance. New vendors are registered under Vendor management (KYC starts as pending). Approve, reject, or suspend below.

Pending vendor verification

All vendors

Commission / deduction

Default rate applies to all orders. Category rules use the higher of default or the override for any product category present in the cart (mixed carts use the max applicable rate).

Default rate %

Apply automatic deduction on every order

Category overrides (Super Admin)

Match exact product cat string (e.g. Electronics).

Category name Rate %

Commission & billing

Local subscription tiers for your business (trial and escalating commission). Order commissions are recorded when customers check out on the storefront on this browser.

Vendor management

Register a vendor record (KYC starts as pending).

API reference

Register: POST /api/admin/vendors (vendors.write). KYC queue: Compliance center — GET /api/vendor/pending-verification (vendors.read); approve / reject / suspend require vendors.approve.

Business name Business TIN / tax ID Email Phone Linked user ID (optional)

Shop profile

Storefront seller identity: name, logo, contacts, social links, and pickup coordinates. New and updated products automatically receive the current shop name and logo.

Product management

Manage your product listings and pricing for your registered business category.

Products0

On Discount0

Avg. Discount0%

Total Savings$0.00

CurrencyUSD

Add New Product

Product Images

Click or drag to upload

JPG, PNG, WEBP · stored as data URLs (max 6)

Product Name

Stock management

Loading copy from /api/catalog…

Low-stock threshold (units)

Catalog & payments

Manage the merged storefront category tree (built-in seed + your overlay) and checkout payment methods.

Category overlays: catalog.read to view; catalog.write to add or remove overlay rows via the admin API.

Payment methods: payments.read to view; payments.write to edit or reset the payment-method catalogue (not the category tree).

The merged category JSON is public: GET /api/categories — same payload as /api/public/categories and /shopdesk/categories.

API discovery

Machine-readable lists for integrations, mobile shells, and partner tooling. Open in a new tab.

Core, storefront & reference JSON

Core

GET /api/catalog — all routes, auth modes, optional rbac per path, plus adminApiEndpoints matrix
GET /api/openapi.json — OpenAPI 3.0 sketch (Bearer security on protected routes)
GET /api/health — storage backend, country/payment counts, meta.auditActionCatalog, storefront path hints

Storefront (no auth)

GET /api/categories · GET /api/public/payment-methods (?country=XX optional)
Aliases: /api/store/*, /api/public/*, /shopdesk/* — see GET /api/health (storefront)

Reference JSON (static, for offline UIs)

/audit-action-catalog.json · /admin-api-rbac.json · /permission-glossary.json · GET /api/meta/audit-action-catalog

Category overlay

Adds or replaces categories in the merged tree (same keys as the storefront). Built-in seed categories are read-only here — only overlay rows can be edited or removed. Use Edit in the table to load an overlay into the form below.

Public URLs & admin API

Public merged tree: GET /api/categories (same data as /api/public/categories and /shopdesk/categories).

Admin API: GET /api/admin/catalog-categories, POST /api/admin/catalog-categories, DELETE /api/admin/catalog-categories?name=… — URL-encode name.

Category name Sub-categories (one per line) Sample items (one per line)

Subs and items can be empty. Saving with an existing overlay name replaces that row. Edit in the table loads the overlay into this form.

Payment methods (checkout)

Enable or disable checkout methods, or reset to the seeded catalogue. Changes apply to the public payment list and storefront checkout. Large tables scroll in the panel below.

Public URLs & admin API

Public: GET /api/public/payment-methods (?country=XX optional). Storefront aliases — see GET /api/health (storefront).

Admin API: GET / POST /api/admin/payment-methods, PUT / DELETE /api/admin/payment-methods/:id, POST /api/admin/payment-methods/reset-catalog (payments.write). Also under endpoints in GET /api/catalog.

Mobile payment systems registry

Moved here under Payment Methods. Data source: GET /api/admin/payment-methods/mobile-systems.

Filter

Payment provider APIs

Provider integration routes served by GET /api/admin/payment-methods/provider-apis.

Order management

Inspect orders, commission split, and set status for fulfilment.

Financial management

Revenue vs platform commission from stored orders.

Orders (commission column)

Tax settings

Home country drives default tax rates; customers choose delivery country at checkout. Super Admin can save.

Tax settings API

Read: GET /api/admin/tax-settings — Requires platform.read.
Write: PUT /api/admin/tax-settings — Super Admin only.
Storefront preview: GET /api/public/tax/config — Optional ?country=XX (ISO-2).

Home country (ISO-2) Tax enabled Prices shown as tax-inclusive in storefront labels Override rate % (blank = use country database) VAT / tax registration number (shown on invoices)

Category zero-rating is defined in data/tax-settings.json under categoryRules. You can extend rules via the API or by editing that file (for example, food or electronics categories).

Customer notifications

Toggles control automatic storefront digests (sales, trending, stock, new items, featured shop). Push announcement delivers to the storefront in about half a minute (bell + in-app list; optional browser alert if the customer allowed notifications).

Automatic alerts

Sale & discount Trending Low stock New arrivals Featured shop

Custom announcement

Message Estimated reach

Flash sale (priority banner)

Message

Recent log

Digest preview (sample)

—

Team chat (Super Admin & admins)

Shared channel for all staff with platform access. Everyone sees the same thread — use it to coordinate with Super Admin and other admins. New messages while you are elsewhere trigger a sound (if enabled) and a highlight on this nav item.

Messages

Message

Communications (Deskia)

Phase 1 MVP: Twilio voice/SMS webhooks write activity logs (calls + SMS threads). This admin view reads those logs.

Call log (recent)

Limit

SMS inbox (recent threads)

Limit

Thread detail

Select a thread…

Security center

Login attempts are always recorded.

A live active sessions list and server-side revoke need PostgreSQL: set DATABASE_URL or SHOPDESK_DATABASE_URL, or PGHOST / PGUSER (optional PGPORT, PGDATABASE, PGPASSWORD), run npm run db:migrate, then restart the server.

In file-backed mode, JWT sign-in still works; the Active sessions panel below explains when the session table is unused.

Login log

Active sessions

Audit trail

Who changed commission, created admins, approved vendors, updated orders, adjusted stock, edited catalog overlays, payment methods, and more.

API reference, export & actor email

List: GET /api/admin/audit-log — requires audit.read. Query: limit (default 100, max 500), optional action (exact) or actionPrefix (prefix; ignored if action is set). Use Refresh audit log below with your Bearer token.

Discovery: the list response includes actionCatalog and endpoints. Authenticated GET /api/catalog also exposes auditTrail metadata when available.

Export: GET /api/admin/audit-log/export — requires audit.export. Same action / actionPrefix / limit filters (export max 2500). Query format=json (default) or format=ndjson. Use the download buttons when your role includes export.

Actor email: each entry includes top-level actorEmail when the server can resolve it (staff user row, JWT email on new logs, auth rows, or optional data/audit-actor-email-overrides.json for legacy actorUserId). metadata.actorEmail is not exposed — use top-level actorEmail only.

Load entries

Limit Action prefix Exact action

Entries

Raw JSON

Default: the full GET /api/admin/audit-log object (starts with {), including actionCatalog, endpoints, and entries — same filters as above. Top-level actorEmail on each entry is server-enriched when resolvable. Uncheck Show full API response to show only the pretty-printed entries array ([ … ]).

Documented action types

Emitted by the server when mutating events occur (public checkout orders include order.create).

Blockchain ledger

Client-side simulated chain (Web Crypto, PoW, Merkle roots). Stored in localStorage as shopdesk_blockchain. Super Admin tools: validate, export, import backup.

Account management

Unified view of staff and vendors; blockchain-derived status for protected fields. Multi-sig demo uses OTP 000000.

Search

Overview

All accounts

Vendor approval queue

Multi-signature & recovery

High-risk actions can queue here; confirm with Super Admin OTP.

Reconstruct account from chain user id

OTP delivery diagnostics

Checks server environment for SendGrid/Twilio configuration and whether your admin profile has email/phone.

Test channel

Click \"Run diagnostics\".

AdminDashboard