Skip to main content

​
Overview

The Orders API provides endpoints for creating and managing customer orders. All order endpoints require authentication.

​
GET /api/orders

Retrieve all orders for the authenticated user.

​
Request

Method: GET Path: /api/orders Authentication: JWT token required Headers:
  • Authorization: Bearer <access_token>

​
Response

​
orders
array
Array of order objects for the current user
​
orders[].id
integer
Order’s unique identifier
​
orders[].user_id
integer
User ID who placed the order
​
orders[].status
string
Order status (pending, paid, shipped, delivered, cancelled)
​
orders[].subtotal
number
Order subtotal before tax and discounts
​
orders[].tax
number
Tax amount
​
orders[].discount_amount
number
Discount amount applied
​
orders[].total
number
Total order amount
​
orders[].discount_code
string
Discount code used (if any)
​
orders[].created_at
datetime
Order creation timestamp
​
orders[].updated_at
datetime
Last update timestamp
​
orders[].items
array
Array of order items
​
orders[].items[].id
integer
Order item ID
​
orders[].items[].order_id
integer
Associated order ID
​
orders[].items[].product_id
integer
Product ID
​
orders[].items[].product_name
string
Product name
​
orders[].items[].quantity
integer
Quantity ordered
​
orders[].items[].unit_price
number
Price per unit at time of order
​
orders[].items[].total_price
number
Total price for this item (unit_price × quantity)
​
count
integer
Total number of orders

​
Example

cURL
curl -X GET http://localhost:5000/api/orders \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response (200 OK): 
{
  "orders": [
    {
      "id": 1,
      "user_id": 1,
      "status": "paid",
      "subtotal": 1299.99,
      "tax": 104.0,
      "discount_amount": 0.0,
      "total": 1403.99,
      "discount_code": null,
      "created_at": "2024-01-15T10:00:00",
      "updated_at": "2024-01-15T10:05:00",
      "items": [
        {
          "id": 1,
          "order_id": 1,
          "product_id": 1,
          "product_name": "Laptop Pro 15",
          "quantity": 1,
          "unit_price": 1299.99,
          "total_price": 1299.99
        }
      ]
    }
  ],
  "count": 1
}

​
Error Responses

401 Unauthorized - Missing or invalid token: 
{
  "msg": "Missing Authorization Header"
}

​
GET /api/orders/<id>

Retrieve a specific order by ID.

​
Request

Method: GET Path: /api/orders/<id> Authentication: JWT token required Headers:
  • Authorization: Bearer <access_token>
Path Parameters:
​
id
integer
required
Order ID

​
Response

​
order
object
Order object with all details including items (same structure as orders array above)

​
Example

cURL
curl -X GET http://localhost:5000/api/orders/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Response (200 OK): 
{
  "order": {
    "id": 1,
    "user_id": 1,
    "status": "paid",
    "subtotal": 1299.99,
    "tax": 104.0,
    "discount_amount": 0.0,
    "total": 1403.99,
    "discount_code": null,
    "created_at": "2024-01-15T10:00:00",
    "updated_at": "2024-01-15T10:05:00",
    "items": [
      {
        "id": 1,
        "order_id": 1,
        "product_id": 1,
        "product_name": "Laptop Pro 15",
        "quantity": 1,
        "unit_price": 1299.99,
        "total_price": 1299.99
      }
    ]
  }
}

​
Error Responses

401 Unauthorized - Missing or invalid token: 
{
  "msg": "Missing Authorization Header"
}
404 Not Found - Order not found or doesn’t belong to user: 
{
  "error": "Order not found"
}

​
POST /api/orders

Create a new order.

​
Request

Method: POST Path: /api/orders Authentication: JWT token required Headers:
  • Authorization: Bearer <access_token>
  • Content-Type: application/json
Body Parameters:
​
items
array
required
Array of order items. Must include at least one item.
​
items[].product_id
integer
required
Product ID to order
​
items[].quantity
integer
default:"1"
Quantity to order
​
discount_code
string
Optional discount code to apply

​
Response

​
order
object
Created order object with all details including items

​
Example

cURL
curl -X POST http://localhost:5000/api/orders \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": 1,
        "quantity": 1
      },
      {
        "product_id": 2,
        "quantity": 2
      }
    ],
    "discount_code": "SAVE10"
  }'
Response (201 Created): 
{
  "order": {
    "id": 2,
    "user_id": 1,
    "status": "pending",
    "subtotal": 1359.97,
    "tax": 108.8,
    "discount_amount": 135.99,
    "total": 1332.78,
    "discount_code": "SAVE10",
    "created_at": "2024-01-15T14:30:00",
    "updated_at": "2024-01-15T14:30:00",
    "items": [
      {
        "id": 2,
        "order_id": 2,
        "product_id": 1,
        "product_name": "Laptop Pro 15",
        "quantity": 1,
        "unit_price": 1299.99,
        "total_price": 1299.99
      },
      {
        "id": 3,
        "order_id": 2,
        "product_id": 2,
        "product_name": "Wireless Mouse",
        "quantity": 2,
        "unit_price": 29.99,
        "total_price": 59.98
      }
    ]
  }
}

​
Error Responses

400 Bad Request - Missing items: 
{
  "error": "Order must include at least one item"
}
400 Bad Request - Insufficient stock: 
{
  "error": "Insufficient stock for Laptop Pro 15. Available: 5"
}
401 Unauthorized - Missing or invalid token: 
{
  "msg": "Missing Authorization Header"
}
404 Not Found - Product not found: 
{
  "error": "Product 999 not found"
}

​
Order Processing

When an order is created:
  1. Validation: The system validates that all products exist and have sufficient stock
  2. Calculation: Subtotal, tax, and discounts are calculated automatically
  3. Stock Reduction: Product stock is reduced by the ordered quantity
  4. Status: Order is created with pending status
  5. Payment: Use the Payments API to complete the order
The total is calculated as: 
total = subtotal + tax - discount_amount

Build docs developers (and LLMs) love

Get started for freeTalk to us