🛒 E-Commerce API Documentation

Complete RESTful API Guide for Frontend Developers

✅ API is Running - Version 1.0.0
Base URL: http://ecommerce.saudillc.com:8000

🔐 Authentication

For Protected Routes: Include the JWT token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Token Types:

  • employeeToken - For Admin/Shop Manager (from /api/auth/login)
  • customerToken - For Customers (from /api/customers/login)

🔑 Authentication (Employee)

POST /api/auth/register Public
Request Body:
{ "email": "admin@example.com", // Required "password": "password123", // Required, min 6 chars "firstName": "John", // Optional "lastName": "Doe", // Optional "phone": "+1234567890", // Optional "role": "SHOP_MANAGER" // Optional, defaults to SHOP_MANAGER (ADMIN cannot be created via API) }
Response (201 Created):
{ "success": true, "message": "User registered successfully", "data": { "user": { "id": "user-id", "email": "admin@example.com", "firstName": "John", "lastName": "Doe", "role": "SHOP_MANAGER", "createdAt": "2025-12-07T00:00:00.000Z" }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }
POST /api/auth/login Public
Request Body:
{ "email": "admin@example.com", // Required "password": "password123" // Required }
Response (200 OK):
{ "success": true, "data": { "user": { /* user object */ }, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }
GET /api/auth/me Auth Required
Headers:
Authorization: Bearer YOUR_EMPLOYEE_TOKEN

👤 Customer Authentication

POST /api/customers/register Public
Request Body:
{ "email": "customer@example.com", // Required "password": "password123", // Required, min 6 chars "firstName": "Jane", // Optional "lastName": "Smith", // Optional "phone": "+1234567890", // Optional "birthday": "1990-01-15", // Optional, ISO date "marriageDate": "2020-06-20" // Optional, ISO date }
POST /api/customers/login Public
Request Body:
{ "email": "customer@example.com", "password": "password123" }

📦 Products

GET /api/products Public
Query Parameters:
Parameter Type Required Description
page number Optional Page number (default: 1)
limit number Optional Items per page (default: 10)
categoryId string Optional Filter by category
status string Optional ACTIVE or INACTIVE
POST /api/products Admin Only
Headers:
Authorization: Bearer YOUR_EMPLOYEE_TOKEN Content-Type: application/json
Request Body:
{ "name": "New Product", // Required "slug": "new-product", // Optional - auto-generated if not provided "description": "Product description", // Optional "sku": "PROD-123456", // Optional - auto-generated if not provided "type": "SINGLE", // Optional - SINGLE or VARIATION (default: SINGLE) "price": 99.99, // Required "comparePrice": 149.99, // Optional "stock": 100, // Required "images": ["https://example.com/image1.jpg"], // Optional - array of image URLs "status": "ACTIVE", // Optional - ACTIVE or INACTIVE (default: ACTIVE) "categoryId": "category-id", // Optional - must exist if provided "nameTranslations": { // Optional - multilingual support "en": "New Product", "ar": "منتج جديد" }, "descriptionTranslations": { // Optional "en": "Product description", "ar": "وصف المنتج" } }
Response (201 Created):
{ "success": true, "message": "Product created successfully", "data": { "product": { "id": "product-id", "name": "New Product", "slug": "new-product", "sku": "PROD-123456", "type": "SINGLE", "price": 99.99, "comparePrice": 149.99, "stock": 100, "images": ["https://example.com/image1.jpg"], "status": "ACTIVE", "categoryId": "category-id", "category": { /* category object or null */ }, "variations": [], /* array of variations if type is VARIATION */ "createdAt": "2025-12-07T00:00:00.000Z", "updatedAt": "2025-12-07T00:00:00.000Z" } } }

🛒 Shopping Cart

GET /api/cart Customer Auth
Headers:
Authorization: Bearer YOUR_CUSTOMER_TOKEN
POST /api/cart Customer Auth
Request Body:
{ "productId": "product-id", // Required "variationId": "variation-id", // Optional - required if product type is VARIATION "quantity": 2 // Optional - defaults to 1 }

📋 Orders

POST /api/orders Customer Auth
Request Body:
{ "shippingAddress": { // Required "street": "123 Main Street", "city": "Riyadh", "state": "Riyadh", "zipCode": "12345", "country": "SA", // Required - ISO country code "phone": "+966501234567", // Optional "name": "John Doe" // Optional }, "paymentMethod": "CASH_ON_DELIVERY", // Optional - defaults to CASH_ON_DELIVERY "couponCode": "DISCOUNT10", // Optional "redeemPoints": 0 // Optional - loyalty points to redeem }
Response (201 Created):
{ "success": true, "message": "Order created successfully", "data": { "order": { "id": "order-id", "orderNumber": "ORD-1701878400000-ABC123", "status": "PENDING", "subtotal": 199.98, "discount": 20.00, "tax": 18.00, "shipping": 25.00, "total": 222.98, "shippingAddress": { /* address object */ }, "paymentMethod": "CASH_ON_DELIVERY", "paymentStatus": "PENDING", "orderItems": [ /* array of order items with product details */ ], "createdAt": "2025-12-07T00:00:00.000Z" } } }

📖 Complete Documentation

For complete API documentation with all endpoints, request/response examples, and Postman collection, import E-Commerce_API.postman_collection.json into Postman.

Base URL: http://ecommerce.saudillc.com:8000

Check API Health Status

E-Commerce API v1.0.0 | Built with Node.js & Express

Developed by Saudi Development and Design