Admin Guide

This guide is for platform admins — staff with one of the admin roles (super_admin, admin, curator, or service). It covers the boundaries you control in Kubuli eCommerce.

NOTE

The codebase defines exactly five roles: super_admin, admin, curator, service, merchant. "Platform admin" here means any of the first four. There is no separate "platform-admin" role.

Merchant onboarding & approval

• Merchants submit a place claim (pending).
• You review and set it to approved or rejected.
• Until approved, all merchant APIs return 403.
• Approval has no SLA — it is a manual review.

Storefront & order oversight

• You can view claimed places and their orders.
• Order states: paid → confirmed → completed (or cancelled).

Payments & refunds

• The payment engine is Lunar; payment capture is automatic.
• The Stripe secret key is configured in the admin app only.
• Refunds are admin-only. A merchant attempting a refund receives 403.

WARNING

Do not describe merchant-initiated refunds as possible. They are not.

Disbursements

• notes on disbursements are admin-only.
• Merchants are read-only and receive 404 (not 403) for disbursements that are not theirs.

What admins do NOT do

• No internal API access from the UI. The internal API (/api/internal/*) is gated by X-Internal-Token and is called only by the Hono API service. It is not a public or admin-user surface.
• No automatic payouts. Disbursements are manual via Mobanking.

See the Commerce API Reference and the Operator Guide for setup and rotation procedures.