Orders API

This section documents the RESTful API endpoints for managing orders. You can create, retrieve, update, and delete orders through these endpoints.

GET List All Orders

/orders

Retrieves a list of all orders. Supports filtering and pagination.

Query Parameters

Name Type Required Description
status string Optional Filters orders by their current status (e.g., pending, shipped, delivered, cancelled).
userId integer Optional Filters orders belonging to a specific user ID.
limit integer Optional Maximum number of orders to return. Defaults to 20.
offset integer Optional Number of orders to skip for pagination. Defaults to 0.

Responses

Success Response (200 OK)


[
  {
    "id": 101,
    "userId": 5,
    "orderDate": "2023-10-27T10:00:00Z",
    "totalAmount": 150.75,
    "status": "shipped",
    "items": [
      {
        "productId": 20,
        "quantity": 2,
        "price": 50.25
      },
      {
        "productId": 35,
        "quantity": 1,
        "price": 50.25
      }
    ]
  },
  {
    "id": 102,
    "userId": 8,
    "orderDate": "2023-10-27T11:30:00Z",
    "totalAmount": 75.00,
    "status": "pending",
    "items": [
      {
        "productId": 15,
        "quantity": 3,
        "price": 25.00
      }
    ]
  }
]

Error Response (400 Bad Request)


{
  "error": "Invalid status filter provided."
}

POST Create a New Order

/orders

Creates a new order for the specified user with the given items.

Request Body

The request body should be a JSON object containing the order details.

Field Type Required Description
userId integer Yes The ID of the user placing the order.
items array of objects Yes An array of items to include in the order. Each item object must have productId and quantity.
items[].productId integer Yes The ID of the product.
items[].quantity integer Yes The quantity of the product. Must be greater than 0.

Responses

Success Response (201 Created)


{
  "id": 103,
  "userId": 12,
  "orderDate": "2023-10-27T14:00:00Z",
  "totalAmount": 200.50,
  "status": "pending",
  "items": [
    {
      "productId": 50,
      "quantity": 1,
      "price": 200.50
    }
  ]
}

Error Response (400 Bad Request)


{
  "error": "Invalid input. User ID is missing or items are invalid."
}

Error Response (404 Not Found)


{
  "error": "Product with ID 99 not found."
}

GET Get Order by ID

/orders/{orderId}

Retrieves the details of a specific order by its unique ID.

Path Parameters

Name Type Required Description
orderId integer Yes The unique identifier for the order.

Responses

Success Response (200 OK)


{
  "id": 101,
  "userId": 5,
  "orderDate": "2023-10-27T10:00:00Z",
  "totalAmount": 150.75,
  "status": "shipped",
  "items": [
    {
      "productId": 20,
      "quantity": 2,
      "price": 50.25
    },
    {
      "productId": 35,
      "quantity": 1,
      "price": 50.25
    }
  ]
}

Error Response (404 Not Found)


{
  "error": "Order with ID 999 not found."
}

PUT Update Order Status

/orders/{orderId}/status

Updates the status of an existing order.

Path Parameters

Name Type Required Description
orderId integer Yes The unique identifier for the order.

Request Body

The request body should be a JSON object containing the new status.

Field Type Required Description
status string Yes The new status for the order (e.g., shipped, delivered, cancelled).

Responses

Success Response (200 OK)


{
  "id": 101,
  "userId": 5,
  "orderDate": "2023-10-27T10:00:00Z",
  "totalAmount": 150.75,
  "status": "delivered",
  "items": [
    {
      "productId": 20,
      "quantity": 2,
      "price": 50.25
    },
    {
      "productId": 35,
      "quantity": 1,
      "price": 50.25
    }
  ]
}

Error Response (400 Bad Request)


{
  "error": "Invalid status value provided."
}

Error Response (404 Not Found)


{
  "error": "Order with ID 999 not found."
}

DELETE Cancel Order

/orders/{orderId}

Cancels an existing order. Note: This action is usually irreversible for fulfilled orders.

Path Parameters

Name Type Required Description
orderId integer Yes The unique identifier for the order to cancel.

Responses

Success Response (204 No Content)

Order successfully cancelled. No response body is returned.

Error Response (404 Not Found)


{
  "error": "Order with ID 999 not found."
}

Error Response (409 Conflict)


{
  "error": "Order cannot be cancelled as it has already been shipped."
}