API Reference
Per-role HTTP surface for the Supercommerce backend — store, admin, vendor, and webhooks.
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? }viaResponseInterceptor. Paginated lists useApiWrappedPaginatedResponsewithmetadata.total/limit/offset/hasMore(theResponseInterceptoronly forwards ametadatafield — 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).
| Module | File | Surface |
|---|---|---|
| Affiliate | affiliate.md | Apply / dashboard / link generation / /r/:code redirect / balance + payouts (optional plugin) |
| Banner | banner.md | Public banner read by entity slug |
| Cart | cart.md | Cart resolve, lines, address, coupons, gifts, sync, prepare-checkout, Buy Now (isolated single-item checkout) |
| Catalog | catalog.md | Public categories (incl. tree), brands, tags, ingredients + product detail (PDP) by slug |
| Customer | customer.md | Address book CRUD + default management |
| Dynamic link | dynamic-link.md | CMS link-group by slug |
| Frequently Bought Together | fbt.md | PDP single-anchor + cart multi-anchor co-purchase recommendations (public) |
| Back in stock | back-in-stock.md | "Notify me" on a sold-out variant — subscribe (guest or customer), check, list, withdraw (optional plugin) |
| Global scripts | global-script.md | Enabled head/body script snippets by slot |
| Serviceability | serviceability.md | "Do you deliver to my pincode?" — warn or block verdict + the operator's message (optional plugin) |
| Guest checkout | guest-checkout.md | Anonymous contact capture, account-exists hint, public order tracking (optional plugin) |
| Invoice | invoice.md | Download my order's GST invoice — merged PDF or one vendor's (optional plugin) |
| Notifications | notifications.md | Customer FCM device register/unregister |
| Order | order.md | Provider discovery, place-order, list/detail/cancel, full returns flow |
| Payment — Razorpay | payment-razorpay.md | SDK callback verify |
| Payment — Razorpay Magic | payment-razorpay-magic.md | One-click hosted checkout: start + status poll (optional plugin) |
| Payment — PhonePe | payment-phonepe.md | Post-checkout verify for web + mobile SDK (optional plugin) |
| Reviews | reviews.md | Anonymous list + aggregate, authenticated submit |
| Rewards | rewards.md | Balance + history + cart redemption set/clear (optional plugin) |
| Search | search.md | Faceted product search + autocomplete |
| Settings | settings.md | Public registry-flagged setting reads |
| Shipping | shipping.md | Customer-scoped sub-order tracking timeline |
| Wishlist | wishlist.md | Single "My Wishlist" — list, add, remove, clear, add-to-cart, contains |
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.
| Module | File | Surface |
|---|---|---|
| RBAC | admin-rbac.md | Roles + permissions catalog |
| Affiliate | affiliate.md | Applications, affiliates (suspend / overrides / audit), per-entity overrides, payouts (optional plugin) |
| Audit | audit.md | Unified audit log — every mutating HTTP request + domain event, enriched (geo/device) into ClickHouse; filterable read API (optional plugin) |
| Banner | banner.md | Banner CRUD + soft-delete/restore |
| Cart | cart.md | Cart browse/detail/discard + analytics (funnel, abandonment, cohort) |
| Catalog | catalog.md | Products, variants, brands, categories, tags, ingredients (incl. vendor-request approval) |
| Customer | customer.md | Customer management portal (list/detail, ban/unban, set-role, delete, set-password, session revocation, storefront impersonation) + picker + lifetime-stats recompute |
| Discount | discount.md | Rule CRUD + archive/unarchive |
| Dynamic link | dynamic-link.md | Group + nested-link CRUD, duplicate, reorder |
| Free gift | free-gift.md | AUTOMATIC / BUYXGETY / COUPON_BASED rules |
| Frequently Bought Together | fbt.md | On-demand rebuild trigger + paginated rebuild audit log |
| Global scripts | global-script.md | Head/body script-snippet CRUD + soft-delete/restore |
| Google Merchant | google-merchant.md | OAuth lifecycle, data sources, bootstrap, items list/detail/resync/delete + live Merchant API probe (optional plugin) |
| Invoice | invoice.md | Per-vendor GST invoice download (merged or single) + force regenerate (invoice:view / invoice:regenerate, optional plugin) |
| Klaviyo | klaviyo.md | Connect/disconnect + profile/event/catalog/category/coupon sync triage, resync, bootstrap (optional plugin) |
| Meta Catalog | meta.md | OAuth lifecycle, business/catalog selection with System User token mint, bootstrap, items list/detail/resync/delete-from-meta + live Graph probe; async items_batch + handle poller (optional plugin) |
| Notifications | notifications.md | Broadcast send/list/detail/cancel + log audit |
| Stock notifications | back-in-stock.md | Who is waiting on which sold-out variant + withdraw on their behalf (stockNotification:read / :delete, optional plugin) |
| Order | order.md | Order admin (cancel/mark-paid/refund/events/stale sweep), returns override, payout ledger/draft/promote |
| Payment gateways | payment-gateways.md | Option feeds: registered gateways with per-platform enablement + configured state, and the selectable checkout options |
| Payment — PhonePe | payment-phonepe.md | Operator guide: configuration keys, enabling at checkout, gateway refunds (no PhonePe-specific endpoints — optional plugin) |
| Product attribute | product-attribute.md | Attribute + attribute-group CRUD |
| Reviews | reviews.md | Moderation: approve/reject/spam/admin-create/soft-delete |
| Serviceability | serviceability.md | Delivery deny-list — bulk add/edit/remove pincodes that warn or block at checkout (serviceability:*, optional plugin) |
| Rewards | rewards.md | Customer search + balance/ledger + master ledger log + manual credit/debit (optional plugin) |
| Search | search.md | Async reindex backfill |
| Search Analytics | search-analytics.md | Customer search activity: KPIs, top/zero-result terms, trend, raw events (optional plugin) |
| Settings | settings.md | Admin + store scope CRUD + platform-vendor overrides |
| Shipping | shipping.md | Platform override of per-vendor shipping config |
| Shipping — Clickpost | shipping-clickpost.md | Platform (central warehouse) ClickPost account — credentials, pickup, courier map, active-courier lookup |
| Tax | tax.md | Platform override of per-vendor flat-tax lines |
| Vendor | vendor.md | Application list/approve/reject + vendor directory |
Vendor — /vendor/**
Seller self-service surface. Auth = vendor session; every endpoint scopes to req.vendor.id.
| Module | File | Surface |
|---|---|---|
| Cart | cart.md | Vendor-scoped cart browse + analytics (read-only) |
| Catalog | catalog.md | Products, variants, tabs, catalog-requests (full CRUD within vendor scope) |
| Inventory | inventory.md | Per-variant snapshot/policy/adjustments/movements, listing, CSV import |
| Invoice | invoice.md | Download + regenerate my sub-order's GST invoice (optional plugin) |
| Notifications | notifications.md | Vendor FCM device register/unregister |
| Order | order.md | Sub-order fulfill/cancel/deliver, returns lifecycle, payouts read |
| Product attribute | product-attribute.md | Read-only attribute + group browse |
| Reviews | reviews.md | Moderation gated by admin allow-flags |
| Settings | settings.md | Admin + store scope read/group/bulk-update with gating |
| Shipping | shipping.md | Providers list, config, per-sub-order tracking |
| Shipping — Clickpost | shipping-clickpost.md | Credentials + pincode + courier allow-list + webhookUrl |
| Tax | tax.md | Flat tax row replace |
| Vendor | vendor.md | Registration wizard (single submit) + slug availability + my-applications history |
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).
| Source | File | Surface |
|---|---|---|
| Razorpay → us | payment-razorpay.md | payment.captured / payment.failed reconcile, HMAC-SHA256 |
| Razorpay Magic → us | payment-razorpay-magic.md | Completion webhook + the three modal callbacks (coupons, shipping), HMAC-SHA256 (optional plugin) |
| PhonePe → us | payment-phonepe.md | Order + refund lifecycle, SHA256(username:password), dedup on a composed event id (optional plugin) |
| Clickpost → us | shipping-clickpost.md | Shipment status updates, per-vendor + platform HMAC, dedup on (provider_id, external_event_id) |
| Klaviyo → us | klaviyo.md | Marketing-consent mirror (profile.suppressed / profile.unsuppressed), HMAC-SHA256, dedup on event id (optional plugin) |
| Storage (cross-role) | storage.md | POST /storage/presigned — presigned S3 PUT for any authenticated session |