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:
12500is 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_sessionfor the dashboard (12 hours),souq_customerfor 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.