API REFERENCE
Admin and branding
Two surfaces that sit outside normal merchant billing: operator monitoring for platform staff, and branding for how a merchant appears to its own customers.
Operator access
Every /admin route requires a signed-in user whose email appears in PLATFORM_ADMIN_EMAILS. Non-admin calls return 403.
To use it: set PLATFORM_ADMIN_EMAILS on the backend to one or more comma-separated addresses, restart the API, then sign in to the dashboard with one of those addresses and open /admin. The operator surface checks the allow-list on every request, so removing an address takes effect on the next call.
Monitoring
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /admin/overview | Merchant, user, customer, subscription and invoice counts with the beta queue and recent merchants. | — |
| GET | /admin/health | Database latency, queued and failed email, pending webhooks, failed jobs and integration flags. | — |
| GET | /admin/merchants | Paginated merchant list with search, status and country filters. | — |
| GET | /admin/merchants/:merchantId | Merchant detail with branding, members, gateways and totals. | — |
| PATCH | /admin/merchants/:merchantId/status | Set active, suspended, pending or closed. | — |
| GET | /admin/users | Paginated users with their primary membership. | — |
| PATCH | /admin/users/:userId/status | Set active, suspended or disabled. | — |
| GET | /admin/analytics/platform | Daily platform series and country, provider and plan distributions. | — |
| GET | /admin/notifications | In-app notification feed across merchants. | — |
Beta queue
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /admin/beta-applications | Applications with per-status counts. Filters: status, search. | — |
| GET | /admin/beta-applications/:applicationId | Full application including internal notes. | — |
| PATCH | /admin/beta-applications/:applicationId | Set status or internal notes. Approving queues an approval email. | — |
Valid statuses are pending, reviewing, approved, rejected and onboarded. Status changes are recorded on the application, and the applicant receives an acknowledgment when they apply and a decision email when approved.
Email outbox
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /admin/email-notifications | Outbox monitor with status and template filters. | — |
| POST | /admin/email-notifications/:notificationId/retry | Re-dispatch a queued or failed message. | — |
| POST | /admin/email-notifications/test | Send a test message to a given address. | — |
Merchant branding
Branding affects invoices and customer-facing surfaces. Reads need settings:read, writes need settings:write.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /merchants/:merchantId/branding | Company name, display name, tagline, colours, support email and logo state. | settings:read |
| PATCH | /merchants/:merchantId/branding | Update display name, tagline, hex colours, support email and invoice logo flag. | settings:write |
| POST | /merchants/:merchantId/branding/logo | Multipart upload in the `logo` field of a PNG, JPEG, WebP or SVG up to 2 MB. | settings:write |
| DELETE | /merchants/:merchantId/branding/logo | Remove the logo. | settings:write |
| GET | /public/merchants/:merchantId/branding | Public JSON: display name, colours and the absolute `logoUrl` for checkout and invoices. | — |
| GET | /public/merchants/:merchantId/branding/logo | Public image bytes with ETag and cache headers; `?download=1` forces a download. | — |
Use the absolute logoUrl the API returns rather than building one from the merchant ID, so caching and versioning keep working. Logo files are checked by magic bytes rather than extension. Transparency is detected, and the response includes logo.hasTransparency plus a recommendation when a flat image would sit badly on an invoice. The public URL is cache-busted with ?v=<timestamp>, and SVGs are served with a locked-down content security policy.