ORDER_API_QUICK_REF.md

Order API Quick Reference

Endpoints

1. Create Order

POST /orders/create
Authorization: Bearer <customer_token>

Request Body:

{
  "items": [
    {
      "catalogue_id": "string",
      "quantity": 1
    }
  ],
  "shipping_address": {
    "address_type": "shipping",
    "line1": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "India"
  },
  "billing_address": {  // Optional, defaults to shipping
    "address_type": "billing",
    "line1": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "India"
  },
  "customer_name": "string",
  "customer_phone": "string",
  "customer_email": "string",
  "payment_method": "string",
  "notes": "string"
}

Response (201):

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "sales_order_id": "uuid",
    "order_number": "ORD-20260207-0001",
    "merchant_id": "uuid",
    "order_date": "2026-02-07T10:30:00",
    "status": "pending",
    "customer_id": "string",
    "subtotal": 1000.00,
    "total_tax": 180.00,
    "grand_total": 1180.00,
    "payment_status": "pending",
    "fulfillment_status": "pending",
    "items": [...],
    "addresses": [...]
  }
}

---

2. Get Order Details

GET /orders/{order_id}
Authorization: Bearer <customer_token>

Response (200):

{
  "success": true,
  "data": {
    "sales_order_id": "uuid",
    "order_number": "ORD-20260207-0001",
    "status": "pending",
    "grand_total": 1180.00,
    "items": [
      {
        "id": "uuid",
        "product_id": "CAT-001",
        "product_name": "Product Name",
        "quantity": 2,
        "unit_price": 500.00,
        "line_total": 1180.00
      }
    ],
    "addresses": [...]
  }
}

---

3. List Orders (Simple)

GET /orders/?skip=0&limit=10
Authorization: Bearer <customer_token>

Response (200):

{
  "success": true,
  "data": {
    "total": 25,
    "orders": [...]
  }
}

---

4. List Orders (Advanced with Projection)

POST /orders/list
Authorization: Bearer <customer_token>

Request Body:

{
  "filters": {
    "status": "pending",
    "payment_status": "pending",
    "fulfillment_status": "pending"
  },
  "skip": 0,
  "limit": 10,
  "projection_list": [
    "sales_order_id",
    "order_number",
    "order_date",
    "status",
    "grand_total",
    "payment_status"
  ],
  "sort_by": "created_at",
  "sort_order": "desc"
}

Response (200):

{
  "total": 25,
  "skip": 0,
  "limit": 10,
  "orders": [
    {
      "sales_order_id": "uuid",
      "order_number": "ORD-20260207-0001",
      "order_date": "2026-02-07T10:30:00",
      "status": "pending",
      "grand_total": 1180.00,
      "payment_status": "pending"
    }
  ]
}

---

Order Statuses

Order Status

• pending - Order created, awaiting confirmation
• confirmed - Order confirmed by merchant
• processing - Order being prepared
• shipped - Order shipped
• delivered - Order delivered
• cancelled - Order cancelled

Payment Status

• pending - Payment not received
• paid - Payment completed
• failed - Payment failed
• refunded - Payment refunded

Fulfillment Status

• pending - Not yet fulfilled
• processing - Being prepared
• shipped - Shipped to customer
• delivered - Delivered to customer
• cancelled - Fulfillment cancelled

---

Error Responses

400 Bad Request

{
  "detail": "Product not found: CAT-001"
}

401 Unauthorized

{
  "detail": "Could not validate credentials"
}

403 Forbidden

{
  "detail": "This endpoint requires customer authentication"
}

404 Not Found

{
  "detail": "Order not found"
}

---

Authentication

Get customer token from auth-ms:

# 1. Request OTP
curl -X POST "http://localhost:8001/auth/customer/request-otp" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+919876543210"}'

# 2. Verify OTP and get token
curl -X POST "http://localhost:8001/auth/customer/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "otp": "123456"
  }'

# Response includes access_token
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer"
}

---

Testing with cURL

Create Order

curl -X POST "http://localhost:8000/orders/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"catalogue_id": "CAT-001", "quantity": 2}],
    "shipping_address": {
      "address_type": "shipping",
      "line1": "123 Main St",
      "city": "Mumbai",
      "state": "Maharashtra",
      "postal_code": "400001",
      "country": "India"
    },
    "customer_name": "John Doe",
    "payment_method": "cod"
  }'

Get Order

curl -X GET "http://localhost:8000/orders/ORDER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

List Orders with Projection

curl -X POST "http://localhost:8000/orders/list" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projection_list": ["order_number", "status", "grand_total"],
    "limit": 5
  }'

---

Python Example

import requests

# Get token
token_response = requests.post(
    "http://localhost:8001/auth/customer/verify-otp",
    json={"phone_number": "+919876543210", "otp": "123456"}
)
token = token_response.json()["access_token"]

# Create order
headers = {"Authorization": f"Bearer {token}"}
order_data = {
    "items": [{"catalogue_id": "CAT-001", "quantity": 2}],
    "shipping_address": {
        "address_type": "shipping",
        "line1": "123 Main St",
        "city": "Mumbai",
        "state": "Maharashtra",
        "postal_code": "400001",
        "country": "India"
    }
}

response = requests.post(
    "http://localhost:8000/orders/create",
    headers=headers,
    json=order_data
)

order = response.json()["data"]
print(f"Order created: {order['order_number']}")

---

Database Tables

trans.sales_orders

Main order table with customer, merchant, and financial information.

trans.sales_order_items

Order line items with product details, quantities, and pricing.

trans.sales_order_addresses

Shipping and billing addresses for orders.

---

Key Features

✅ Customer JWT authentication
✅ Product validation from MongoDB
✅ Single merchant per order validation
✅ Automatic tax calculation
✅ Unique order number generation
✅ PostgreSQL persistence (trans schema)
✅ Projection list support (API standard)
✅ Filtering and sorting
✅ Comprehensive error handling