API Reference

Per-role split of the API documentation. Each module's HTTP surface is documented separately for the storefront (customer-facing), admin (platform operator), vendor (seller self-service), and webhooks (inbound from external providers) audiences.

Canonical, full-module docs still live in ../*.md (cart.md, order.md, etc.). The files here are role-scoped slices of those docs — useful for client teams that only build against one surface.

---

Conventions (shared)

• Response envelope — { data, message, statusCode, metadata? } via ResponseInterceptor. Paginated lists use ApiWrappedPaginatedResponse with metadata.total/limit/offset/hasMore (the ResponseInterceptor only forwards a metadata field — a handler that returns any other key, e.g. pagination, has it dropped).
• Money — integer subunits (paise / cents). Single currency per tenant.
• Dates — ISO 8601 strings (z.iso.datetime() at the DTO layer; dayjs().toDate() in services).
• Auth — better-auth sessions. Storefront uses customer sessions, admin uses admin sessions with RBAC permission checks, vendor uses vendor sessions scoped to req.vendor.id.
• Multi-tenant — vendor endpoints scope every read/write to the session's vendor. Cross-vendor ids return 404, never 403, so existence of other tenants' data can't be inferred.

---

Store — /store/** and public reads

Customer-facing surface. Auth = customer session (or public for catalog/banner/dynamic-link reads).

---

Admin — /admin/**

Platform operator surface. Auth = admin session + RBAC permission strings (e.g. user: list, product: create). Permission codes are documented per-endpoint and indexed in admin-rbac.md.

---

Vendor — /vendor/**

Seller self-service surface. Auth = vendor session; every endpoint scopes to req.vendor.id.

---

Webhooks — inbound from external providers

Signed inbound surface. Each provider has its own signature scheme; secrets live in admin or per-vendor settings (not env vars).