Cart and delivery

Logged-in carts are keyed by customer (Bearer JWT). Guests use an opaque cart token. Delivery is stored on the cart.

Shopper	Cart identity
Guest	X-Cart-Token (value from results.cartToken)
Signed in	JWT only — do not send X-Cart-Token

GET /v1/cart returns cartToken. Persist it while the shopper is a guest. After OTP login, guest cart and delivery are merged onto the customer.

Guests can mutate the cart. Placing an order still requires a customer JWT.

Cart

Prefix: /v1/cart. Auth: Public (JWT optional).

Method	Path	Body	Purpose
GET	/v1/cart	—	Read cart + totals
POST	/v1/cart/items	{ items: [{ productId, variantId?, quantity }] }	Add 1–50 lines
PATCH	/v1/cart/items/:key	quantity update	Change a line
DELETE	/v1/cart/items/:key	—	Remove a line
POST	/v1/cart/coupon	{ code }	Apply coupon
DELETE	/v1/cart/coupon	—	Clear coupon
POST	/v1/cart/loyalty	{ points }	Redeem points (customer)
DELETE	/v1/cart/loyalty	—	Clear points
POST	/v1/cart/express	{ enabled: true | false }	Toggle express
DELETE	/v1/cart	—	Empty the cart

Line key comes from the cart payload. Use it for PATCH/DELETE.

Add items example

POST /v1/cart/items
Content-Type: application/json
X-Cart-Token: <cartToken>

{
  "items": [
    { "productId": "665f0c0c0c0c0c0c0c0c0c0c", "quantity": 2 }
  ]
}

Totals, fees, and offer lines are computed server-side. Trust results, do not re-price on the client.

OUT_OF_STOCK and CART_EMPTY are common domain errors.

Delivery

Prefix: /v1/delivery. Auth: Public. Send X-Cart-Token while guest, Bearer when signed in.

Method	Path	Body	Purpose
GET	/v1/delivery/areas	—	Deliverable areas
GET	/v1/delivery/branches	—	Pickup branches
GET	/v1/delivery/slots	—	Bookable slots (Kuwait dates)
POST	/v1/delivery/select	Delivery selection payload	Set delivery mode / area
POST	/v1/delivery/select-branch	Pickup branch	Set pickup mode
POST	/v1/delivery/select-address	{ addressId }	Use a saved address (customer)
POST	/v1/delivery/resolve-location	{ lat, lng }	Pin → branch + zone

Resolve location example

POST /v1/delivery/resolve-location
Content-Type: application/json
X-Cart-Token: <cartToken>

{ "lat": 29.3759, "lng": 47.9774 }

Results include mode: "delivery", branchId, zoneId, deliveryFee, minOrder, etaMinutes (fees in fils).

Select / select-branch / select-address / resolve-location patch the cart (fulfillmentMode, branchId, zoneId, addressId, lat, lng).

Select saved address

POST /v1/delivery/select-address
Content-Type: application/json
Authorization: Bearer <accessToken>

{ "addressId": "665f0c0c0c0c0c0c0c0c0c0d" }

Requires a customer JWT and an address on that account.

Slots

GET /v1/delivery/slots returns days:

• date — YYYY-MM-DD in Asia/Kuwait
• slots[] — templateId, start, end, remaining, available, localized label

When placing a scheduled delivery order, send deliverySlot: { templateId, date }. Omit the slot for pickup, express, or ASAP flows.