For: Full Stack · Backend API

API reference

Every endpoint of the Souq API, with its body, answer and who may call it.

The API is under /api. It sends and receives JSON. The storefront and the dashboard use it, and you can use it from a mobile app or another system.

Conventions

  • Money is always an integer in the currency's smallest unit: 12500 is OMR 12.500.
  • Errors answer with an HTTP status and {"error": {"code": "...", "message": "..."}}. Common codes: validation (422, the message lists each problem), unauthorized (401), forbidden (403), not_found (404), conflict (409, duplicate slug, SKU, code or email), rate_limited (429).
  • Sessions are httpOnly cookies: souq_session for the dashboard (12 hours), souq_customer for shoppers (30 days). Send the cookie back on later requests.
  • PATCH changes only the fields you send; fields you leave out keep their value. PUT replaces the whole record.
  • Rate limits per visitor IP: checkout 20/min, quote 120/min, coupon check 20/min, tracking lookup 10/min, sign-in 10/min (and 8 wrong passwords per 15 minutes per email), registration 5/min, contact form 5 per 10 minutes.

Store (public)

Method and path What it does
GET /api/store Store names, currency, VAT, payment methods available, shipping methods, governorates
GET /api/categories Visible categories with their product counts
GET /api/collections Visible curated edits with their product counts
GET /api/products Product list. Query: category, collection, q, cat, new, sale, featured, size, color, min, max, stock, sort, page, perPage (max 60). Answers {products, page, pages, total, facets}
GET /api/products/{slug} One product with every variant (id, sku, size, colour, price, stock) and related products

Cart and orders (public)

POST /api/cart/quote prices a cart without saving anything:

{ "items": [{ "variantId": "...", "quantity": 2 }], "couponCode": "WELCOME10", "governorate": "muscat", "shippingMethod": "muscat-standard" }

Answer: lines (each with unitPrice, lineTotal, stock and an issue when it cannot be bought), coupon (ok, discount or reason), shipping.options for the governorate, subtotal, discount, shippingFee, tax, total, and ok.

POST /api/coupons/validate {code, items} answers {valid, discount} or {valid: false, reason, message}.

POST /api/orders places an order:

{
  "items": [{ "variantId": "...", "quantity": 1 }],
  "couponCode": "",
  "customerName": "Aisha Al Balushi", "phone": "+968 9123 4567", "email": "",
  "governorate": "muscat", "city": "Al Khuwair", "addressLine": "Way 2601, Building 12", "notes": "",
  "shippingMethod": "muscat-standard", "paymentMethod": "COD", "locale": "ar"
}

Answers 201 {code, total}, plus payUrl for "paymentMethod": "CARD" (send the customer there). Errors: out_of_stock (409), coupon_invalid, shipping_unavailable, payment_disabled, invalid_phone (422), not_accepting (409), payment_unavailable (502). If a shopper is signed in, the order is linked to their account.

Method and path What it does
GET /api/orders/{code} Order status for the customer: items, totals, timeline; the phone is partly hidden
POST /api/orders/lookup {code, phone}: the same, only if the phone matches the order
GET /api/payments/thawani/return?order=CODE Where Thawani sends the customer back; verifies the payment with Thawani and redirects to the order page
POST /api/contact {name, email, phone?, subject?, message}: saves a message for the dashboard

Shopper accounts

Method and path What it does
POST /api/account/register {name, email, password (8+), phone?}: creates the account and signs in. email_taken (409) if it exists
POST /api/account/login {email, password}
POST /api/account/logout Signs out
GET /api/account/me {customer, orders, wishlist} (401 when signed out)
PATCH /api/account/me {name?, phone?}
GET /api/account/wishlist {customer, productIds}; customer is null when signed out
POST /api/account/wishlist {productId} adds
DELETE /api/account/wishlist {productId} removes

Dashboard

All dashboard endpoints need the souq_session cookie. The permission in brackets must be allowed for the account's role (Admin roles); the owner may always.

Method and path Permission What it does
POST /api/auth/login {email, password}: signs in, answers {user: {name, email, role}}
POST /api/auth/logout Signs out
GET /api/auth/me signed in The signed-in account
GET /api/dashboard/stats signed in Everything on the overview
GET /api/dashboard/orders orders ?status= (a status or OPEN), q, page, perPage
GET /api/dashboard/orders/{id} orders Full order with timeline and next (allowed statuses)
PATCH /api/dashboard/orders/{id} orders {status, note?} moves the order; bad_transition (409) if not allowed
GET, POST /api/dashboard/products products List (?q=&categoryId=); create with variants
GET, PUT, PATCH, DELETE /api/dashboard/products/{id} products PUT replaces the product and its variant list (variants with an id are updated, new ones created, missing ones deleted). PATCH accepts active, featured, price, compareAt, sort, categoryId, stock: [{id, stock}]
POST /api/dashboard/uploads products multipart/form-data field file: an image up to 5 MB; answers {url}
GET, POST /api/dashboard/categories catalog
PUT, PATCH, DELETE /api/dashboard/categories/{id} catalog Delete only when no product uses it
GET, POST /api/dashboard/collections catalog
PUT, PATCH, DELETE /api/dashboard/collections/{id} catalog
GET, POST /api/dashboard/coupons coupons {code, type, value, minOrder?, expiresAt?, usageLimit?, active?}; type is PERCENT or FIXED
PUT, PATCH, DELETE /api/dashboard/coupons/{id} coupons The usage count is kept
GET /api/dashboard/customers customers ?q=; accounts and guests grouped by phone
GET /api/dashboard/messages customers ?open=1 for unhandled only
PATCH, DELETE /api/dashboard/messages/{id} customers {handled}
GET, POST /api/dashboard/ai/chat ai GET: {configured, insights}; POST {messages: [{role, content}], locale} answers {reply} (501 without AI)
GET, POST /api/dashboard/ai/describe ai POST {nameAr, nameEn, category?, notes?, tone?} answers {ar, en}
GET /api/dashboard/settings signed in Settings, and whether the Thawani keys are set
PUT, PATCH /api/dashboard/settings settings
GET, POST /api/dashboard/admins admins {name, email, password (10+), role}; only an owner creates an owner
PATCH, DELETE /api/dashboard/admins/{id} admins {name?, role?, active?, password?}
GET /api/dashboard/roles signed in {permissions, matrix, mine}
PUT /api/dashboard/roles owner only {ADMIN: [...], STAFF: [...]}

Example

# sign in and keep the cookie
curl -c jar.txt -H "Content-Type: application/json" \
  -d '{"email":"owner@souq.test","password":"souq-demo-2026"}' http://localhost:3302/api/auth/login

# hide a product without touching anything else
curl -b jar.txt -X PATCH -H "Content-Type: application/json" \
  -d '{"active":false}' http://localhost:3302/api/dashboard/products/PRODUCT_ID

scripts/e2e_api.py exercises almost every endpoint and is a good place to see real requests and answers.