Skip to main content
POST
/
orders
curl --location 'http://localhost:3000/orders' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerEmail": "[email protected]",
  "items": [
    {
      "productId": 1,
      "quantity": 2
    },
    {
      "productId": 3,
      "quantity": 1
    }
  ]
}'

{
  "id": 1,
  "customerEmail": "[email protected]",
  "totalAmount": "45.50",
  "status": "PENDING",
  "createdAt": "2026-03-10T10:30:00.000Z",
  "items": [
    {
      "id": 1,
      "orderId": 1,
      "productId": 1,
      "quantity": 2,
      "unitPrice": "15.50"
    },
    {
      "id": 2,
      "orderId": 1,
      "productId": 3,
      "quantity": 1,
      "unitPrice": "14.50"
    }
  ]
}
Creates a new order with the status PENDING. The total amount is automatically calculated based on the current product prices and quantities. The operation is performed within a database transaction to ensure data consistency.

​
Validation Rules

  • Order must contain at least one item
  • All products must exist and be active
  • Product IDs must be unique within the order
  • Quantities must be at least 1

​
Request Body

​
customerEmail
string
required
Valid email address of the customer placing the orderValidation: Must be a valid email format
​
items
array
required
Array of order items. Must contain at least one item.
​
productId
integer
required
ID of the product to order. Must reference an active product.Validation: Minimum value of 1
​
quantity
integer
required
Quantity of the product to orderValidation: Minimum value of 1

​
Response

​
id
integer
Unique identifier for the created order
​
customerEmail
string
Customer’s email address
​
totalAmount
decimal
Calculated total amount based on product prices and quantities
​
status
enum
Order status. Will always be PENDING for newly created orders
​
createdAt
datetime
Timestamp when the order was created
​
items
OrderItem[]
Array of created order items
​
id
integer
Unique identifier for the order item
​
productId
integer
ID of the ordered product
​
quantity
integer
Quantity ordered
​
unitPrice
decimal
Unit price at the time of order creation
​
orderId
integer
Reference to the parent order
curl --location 'http://localhost:3000/orders' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customerEmail": "[email protected]",
  "items": [
    {
      "productId": 1,
      "quantity": 2
    },
    {
      "productId": 3,
      "quantity": 1
    }
  ]
}'

{
  "id": 1,
  "customerEmail": "[email protected]",
  "totalAmount": "45.50",
  "status": "PENDING",
  "createdAt": "2026-03-10T10:30:00.000Z",
  "items": [
    {
      "id": 1,
      "orderId": 1,
      "productId": 1,
      "quantity": 2,
      "unitPrice": "15.50"
    },
    {
      "id": 2,
      "orderId": 1,
      "productId": 3,
      "quantity": 1,
      "unitPrice": "14.50"
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us