Getting started

Base URLs

Environment	Public API (customer)	Admin API (picker / driver)
Local	http://localhost:5000	http://localhost:5001
Version prefix	/v1	/v1

Example: list products is GET http://localhost:5000/v1/products.

Headers

Header	Required	Notes
Content-Type: application/json	On JSON bodies
Accept-Language	Recommended	ar or ar-* → Arabic; anything else → English
Authorization: Bearer <accessToken>	After login	Customer or staff access JWT
X-Cart-Token	Customer app, guests	Opaque token from results.cartToken
X-Assistant-Guest	Customer app, guests	32-char hex guest key you generate and persist

Identity, cart, and assistant guest keys travel in these headers (or in JSON for refresh).

Language

Accept-Language is parsed as: starts with ar → ar, otherwise en. Localized catalog strings in Public API responses are already resolved to that language. Admin/core documents still use { en, ar } objects.

Money

All money fields are integers in fils. 1.250 KWD = 1250. Format with three decimal places in the UI.

Pagination

List endpoints that accept paging use:

Query	Default	Max
page	1	—
limit	20	100
search	optional	120 chars

Response meta:

{
  "total": 80,
  "page": 1,
  "limit": 20,
  "hasMore": true
}

Token handling

• After OTP or staff login, persist accessToken + refreshToken (SecureStore). Send Authorization: Bearer <accessToken> on every authenticated request.
• On 401, POST /v1/auth/refresh with { "refreshToken" }, store the new pair, retry once. If refresh fails, send the user to login.
• While the customer is a guest, persist results.cartToken and send X-Cart-Token on cart and delivery calls.
• Language is Accept-Language per request. Do not put cart or delivery inside the JWT.
• Swagger at /docs is generated from the same TypeBox schemas as the routes. Operations are grouped by module. Use Authorize to send a Bearer JWT.

Maintenance mode

When store maintenance is on, mutating /v1/cart, placing/cancelling orders, and wishlist writes return a validation error. Reads still work.