LBLetBuyy Developers
DocsAPISDKsDashboard
API reference

Curated `/v1` gateway surface

The reference is derived from the Hono route mounts and route modules in `services/api-gateway/src`. It lists the real route families, auth model, pagination conventions, errors, and query-cost rate limits currently implemented.

Live

Gateway Mounts

The Hono worker mounts its public and protected surface under `/v1`, with `/health` outside the API version.

services/api-gateway/src/index.ts
GET /health
/v1/auth
/v1/storefront
/v1/stores
/v1/products
/v1/orders
/v1/payments
/v1/themes
/v1/app-store
/v1/operations
Live

Auth and Sessions

Merchant identity endpoints include signup, signin, OTP, password reset/update, custom session validation, and identity-platform helpers.

services/api-gateway/src/routes/auth.ts
POST /v1/auth/signup
POST /v1/auth/signin
POST /v1/auth/signin/otp
POST /v1/auth/signin/otp/verify
POST /v1/auth/signout
POST /v1/auth/password/reset
POST /v1/auth/password/update
GET /v1/auth/custom/session
Live

Commerce Admin

Store-scoped merchant APIs cover products, collections, gift cards, orders, refunds, fulfillment, customers, addresses, reviews, coupons, inventory, media, and forms.

services/api-gateway/src/routes/products.ts, orders.ts, customers.ts
GET|POST /v1/products
GET|POST /v1/products/collections
GET|POST /v1/products/gift-cards
GET|POST /v1/orders
POST /v1/orders/:id/fulfill
POST /v1/orders/:id/refund
GET /v1/customers
GET|POST /v1/inventory/locations
GET /v1/form-submissions
Live

Storefront Runtime

Public storefront APIs resolve stores, products, categories, navigation, policies, persisted carts, checkout order creation, provider payment operations, customer accounts, wishlist, addresses, and reviews.

services/api-gateway/src/routes/storefront.ts
GET /v1/storefront/lookup
GET /v1/storefront/:subdomain
GET /v1/storefront/:subdomain/products
GET|POST|PATCH|DELETE /v1/storefront/:subdomain/cart
POST /v1/storefront/:subdomain/orders
POST /v1/storefront/:subdomain/payments/razorpay/order
POST /v1/storefront/customer/login
GET|POST|PATCH|DELETE /v1/storefront/customer/addresses
Partial

GraphQL APIs

Admin and Storefront GraphQL endpoints are mounted behind the gateway with query-cost limiting. Storefront cart reads delegate to the persisted cart-token REST contract; writes remain on REST.

services/api-gateway/src/graphql/schema.ts, storefront.ts, admin.ts
GET|POST /v1/admin/graphql
GET|POST /v1/graphql/admin
GET|POST /v1/storefront/graphql
GET|POST /v1/graphql/storefront
StorefrontQuery.cart -> persisted cart token
Admin bulk operations -> Cloudflare R2 JSONL
Live

Theme Platform

Theme APIs cover marketplace catalog, JSON-contract package upload, Liquid/JSON rendering assets, install, multi-template editor state, draft save/delete, preview tokens, release history, rollback, purchase, and payment verification.

services/api-gateway/src/routes/themes.ts
GET /v1/themes
GET /v1/themes/:slug/schema
GET /v1/themes/:slug/editor
PUT /v1/themes/:slug/editor/draft
POST /v1/themes/:slug/preview-session
POST /v1/themes/packages/upload
POST /v1/themes/:slug/install
POST /v1/themes/:slug/purchase/verify
Live

App Platform

App marketplace APIs include catalog, reviews, installation, extension/function lifecycle registry, app bridge fetch, OAuth authorization code, token exchange, developer profile, developer app submissions, and partner dashboard aggregates.

services/api-gateway/src/routes/app-store.ts
GET /v1/app-store/apps
POST /v1/app-store/apps/:id/install
GET /v1/app-store/installations/:id/extensions
PATCH /v1/app-store/installations/:id/extensions/:registrationId
PATCH /v1/app-store/installations/:id/functions/:registrationId
POST /v1/app-store/apps/:id/oauth/authorize
POST /v1/app-store/oauth/token
POST /v1/app-store/oauth/token-exchange
POST /v1/app-store/bridge/fetch
GET|POST /v1/app-store/developers/register
GET /v1/app-store/partners/dashboard
Live

Operations and Webhook Admin

Operational APIs expose outbox, webhook deliveries/subscriptions, runtime queues, replays, incidents, failover drills, load tests, certification reports, and SRE evidence.

services/api-gateway/src/routes/operations.ts
GET /v1/operations/webhook-deliveries
GET|POST /v1/operations/webhook-subscriptions
GET /v1/operations/runtime/overview
GET|POST /v1/operations/runtime/replays
GET|POST /v1/operations/runtime/incidents
POST /v1/operations/runtime/failover-drills
Auth

Authentication

Protected routes use gateway auth middleware. Merchant routes accept Supabase bearer tokens or signed internal LetBuyy session headers; app OAuth routes mint scoped app tokens through app-engine/auth-core contracts.

  • Merchant session cookie name is `lb_session` in auth-core.
  • App access tokens carry normalized scopes and installation/store identity.
  • Internal signed session headers remain backend-owned and must not be generated by browser or mobile clients.
Errors

Error and pagination shape

Known errors use structured bodies with `error.code` and `error.message`. List endpoints use page/limit or route-local query schemas and return paginated payloads where the route calls the shared pagination helper.

  • Common codes include `VALIDATION`, `FORBIDDEN`, `NOT_FOUND`, `DB_ERROR`, `RATE_LIMIT_UNAVAILABLE`, and `QUERY_COST_RATE_LIMITED`.
  • Store-scoped routes require `store_id` or an ownership-resolved store context.
Rate limits

Calculated query-cost model

The gateway uses a leaky-bucket query-cost limiter in non-local runtimes. The model is implemented in `services/api-gateway/src/middleware/rateLimit.ts`.

Query-cost limiting is skipped in local/development runtimes.

Default query-cost bucket: capacity 200, leak rate 20 points per second.

GET and HEAD start at cost 1; POST, PUT, and PATCH start at cost 5; DELETE starts at cost 8.

limit/page_size/first values above 50 add cost; each include or expand item adds 2.

Analytics/export add 15, operations add 10, AI adds 20, and internal routes add 10.

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Cost, and X-RateLimit-Policy.

Accurate to the tracked LetBuyy gateway, app-engine, theme-engine, auth-core, and webhook-service contracts. Planned or absent surfaces are marked as skips.