Skip to main content

Order Service – API Reference 🧾

This document describes the customer and admin APIs exposed by the Order Service in ShopVerse.

All APIs are accessed via the API Gateway.
Authorization is enforced using gateway-injected headers.

🌐 Base URL​


/api/orders

🔐 Authentication & Authorization​

  • JWT is validated at the API Gateway
  • Gateway injects:
    • X-User-Email
    • X-User-Role
  • Customers can access only their own orders
  • Admins can access all orders

🛒 Place Order (Customer)​

Create a new order for the authenticated user.

➤ Endpoint​


POST /api/orders

➤ Request Body​

{
  "items": [
    {
      "productId": "PROD123",
      "quantity": 2
    },
    {
      "productId": "PROD456",
      "quantity": 1
    }
  ]
}

➤ Success Response (201 CREATED)​

{
  "orderId": "ORD789",
  "status": "CREATED",
  "totalAmount": 5497
}

➤ Error Responses​

StatusReason
400Invalid request / insufficient stock
401Unauthorized
500Internal server error

📄 Get Order by ID (Customer / Admin)​

Fetch order details by order ID.

➤ Endpoint​

GET /api/orders/{orderId}

➤ Access Rules​

  • CUSTOMER → only own orders
  • ADMIN → any order

➤ Success Response (200 OK)​

{
  "orderId": "ORD789",
  "customerId": "user@example.com",
  "status": "CREATED",
  "orderDate": "2026-01-21T12:30:00",
  "totalAmount": 5497,
  "items": [
    {
      "productId": "PROD123",
      "quantity": 2,
      "price": 2499
    }
  ]
}

📦 Get My Orders (Customer)​

Fetch all orders placed by the authenticated user.

➤ Endpoint​

GET /api/orders/my

➤ Success Response (200 OK)​

[
  {
    "orderId": "ORD789",
    "status": "CREATED",
    "totalAmount": 5497,
    "orderDate": "2026-01-21T12:30:00"
  }
]

👑 Get All Orders (Admin)​

Fetch all orders in the system.

➤ Endpoint​

GET /api/orders

➤ Role Required​

ADMIN

➤ Success Response (200 OK)​

[
  {
    "orderId": "ORD789",
    "customerId": "user@example.com",
    "status": "CONFIRMED",
    "totalAmount": 5497
  }
]

🔄 Update Order Status (Admin)​

Update the status of an order.

➤ Endpoint​

PUT /api/orders/{orderId}/status

➤ Role Required​

ADMIN

➤ Request Body​

{
  "status": "CONFIRMED"
}

➤ Allowed Status Transitions​

CREATED → CONFIRMED
CONFIRMED → CANCELLED

➤ Success Response (200 OK)​

{
  "message": "Order status updated successfully"
}

🔁 Order Lifecycle​

📡 Events Published​

EventTopicDescription
ORDER_PLACEDorder-eventsNew order created
ORDER_STATUS_UPDATEDorder-eventsOrder status changed

Consumed by:

  • Notification Service
  • Analytics Service
  • Recommendation Service

🔄 Request Flow​

⚠️ Common Errors​

StatusMeaning
400Invalid order / stock issue
401Unauthorized
403Forbidden
404Order not found
409Invalid status transition

📌 Summary​

The Order API provides:

  • Secure order creation
  • Ownership-based access
  • Admin-controlled order lifecycle
  • Event-driven extensibility

It acts as the transactional core of ShopVerse.