API Design Reference

Related docs: Payment Architecture · Data Models · Security Compliance

---

1. Conventions

Convention	Value
Base path	/api/v1/
Data format	application/json
Authentication	Authorization: Bearer <accessToken>
Error format	{ "success": false, "message": "..." }
Success format	{ "success": true, "data": { ... } } or top-level object
Currency	ZMW; represented as number (decimal), displayed as K xxx.xx
Dates	ISO 8601 strings (2026-05-12T10:00:00.000Z)

---

2. Authentication Endpoints

Method	Path	Auth	Description
POST	/auth/register	None	Register with email + password
POST	/auth/login	None	Login; returns accessToken + refreshToken
POST	/auth/logout	Required	Invalidate current session
POST	/auth/refresh	None	Exchange refreshToken for new accessToken
POST	/auth/request-magic-link	None	Send magic link to email
POST	/auth/verify-magic-link	None	Verify magic link token
POST	/auth/request-password-reset	None	Send password reset email
POST	/auth/reset-password	None	Complete password reset
POST	/auth/verify-email	None	Verify email with token
GET	/auth/me	Required	Get authenticated user profile
GET	/oauth/:provider	None	Initiate OAuth flow
GET	/oauth/:provider/callback	None	OAuth callback

---

3. Product Endpoints

Method	Path	Auth	Description
GET	/products	None	List products with filters
GET	/products/:id	None	Single product with variants
GET	/products/recommendations	Optional	Personalised or popular products
GET	/products/:productId/options	None	Product option groups
GET	/products/:productId/variants	None	Product variants

Query params for /products: category, search, minPrice, maxPrice, sort, page, limit, featured, shopId.

---

4. Shop Endpoints

Method	Path	Auth	Description
GET	/shops	None	List approved shops
GET	/shops/search	None	Full-text shop search
GET	/shops/slug/:slug	None	Shop by slug
POST	/shops/request	Required	Request new shop (legacy flow)
GET	/shops/my-shops	Required	Authenticated user's shops
GET	/shops/:shopId/stats	Required	Shop analytics
POST	/shops/:shopId/products	Required	Create product in shop
GET	/shops/:shopId/products	Required	List shop's own products
PUT	/shops/:shopId/products/:id	Required	Update product
DELETE	/shops/:shopId/products/:id	Required	Soft-delete product

---

5. Order Endpoints

Method	Path	Auth	Description
POST	/orders	Required	Create order
GET	/orders/my	Required	Authenticated user's orders
GET	/orders/:id	Required	Single order details
PATCH	/orders/:id/cancel	Required	Cancel order

POST /orders request includes:

• items: array of products, quantities, and prices
• shippingAddress: delivery contact and location details
• paymentMethod: selected provider (MTN, AIRTEL, ZAMTEL, CARD)
• total: order amount

---

6. Payment Endpoints

Method	Path	Auth	Description
POST	/payments/initiate	Required	Initiate payment for an order
GET	/payments/status/:orderId	Required	Get payment + settlement status
POST	/payments/webhook/:provider	None	Receive gateway webhooks
POST	/payments/release/:orderId	Admin	Manually release vendor funds

POST /payments/initiate

Request: Requires orderId, paymentMethod, and phoneNumber (for mobile money).
Response: Returns a transactionId and success message for mobile money, or a redirectUrl for card payments.

GET /payments/status/:orderId

Response: Returns the current settlementStatus (e.g., HELD, RELEASABLE) and a history of payment attempts with their captured status.

---

---

7. Notification Endpoints

Method	Path	Auth	Description
GET	/notifications	Required	List user's notifications
PATCH	/notifications/:id/read	Required	Mark as read
PATCH	/notifications/read-all	Required	Mark all as read
GET	/notifications/preferences	Required	Get user preferences
PUT	/notifications/preferences	Required	Update preferences

---

8. Seller Application Endpoints

Method	Path	Auth	Description
POST	/seller-applications	Required	Create application draft
GET	/seller-applications/my-application	Required	Get own application
PUT	/seller-applications/:id/phase/:phase	Required	Update a phase
POST	/seller-applications/:id/documents	Required	Upload KYC documents
POST	/seller-applications/:id/submit	Required	Submit for review
GET	/seller-applications	Admin	List all applications
PUT	/seller-applications/:id/status	Admin	Update application status
POST	/seller-applications/:id/approve	Admin	Approve; create shop

---

9. Error Response Format

All errors return a consistent shape including a success flag (set to false), a human-readable message, and an optional error code for programmatic handling.

HTTP Status	Meaning
400	Bad request / validation error
401	Unauthenticated
403	Unauthorised (wrong role)
404	Resource not found
409	Conflict (e.g., duplicate order)
429	Rate limit exceeded
500	Internal server error