Skip to main content

​
Get All Orders

Retrieve all orders with populated user and product information. Orders are sorted by creation date (newest first).

​
Authentication

Requires Clerk authentication with admin role. All admin routes are protected by protectRoute and adminOnly middleware.

​
Response

​
orders
array
Array of order objects
​
orders[]._id
string
MongoDB ObjectId
​
orders[].user
object
Populated user object with name and email
​
orders[].clerkId
string
Clerk user ID
​
orders[].orderItems
array
Array of order items with populated product details
​
orderItems[].product
object
Full product object
​
orderItems[].name
string
Product name snapshot
​
orderItems[].price
number
Price at time of order
​
orderItems[].quantity
number
Quantity ordered
​
orders[].shippingAddress
object
Shipping address details
​
shippingAddress.fullName
string
Recipient full name
​
shippingAddress.streetAddress
string
Street address
​
shippingAddress.city
string
City
​
shippingAddress.phoneNumber
string
Phone number
​
orders[].paymentResult
object
Payment information
​
paymentResult.id
string
Payment provider ID (e.g., Stripe payment intent ID)
​
paymentResult.status
string
Payment status
​
orders[].totalPrice
number
Total order price
​
orders[].status
string
Order status (see status enum below)
​
orders[].paidAt
string
ISO 8601 timestamp when order was marked as paid
​
orders[].deliveredAt
string
ISO 8601 timestamp when order was delivered
​
orders[].createdAt
string
ISO 8601 timestamp
​
orders[].updatedAt
string
ISO 8601 timestamp
curl -X GET https://api.example.com/api/admin/orders \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "orders": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "user": {
        "_id": "507f191e810c19729de860ea",
        "name": "Juan Pérez",
        "email": "[email protected]"
      },
      "clerkId": "user_2abcdefghijklmnop",
      "orderItems": [
        {
          "product": {
            "_id": "507f1f77bcf86cd799439012",
            "name": "Empanada de Carne",
            "price": 5000
          },
          "name": "Empanada de Carne",
          "price": 5000,
          "quantity": 3
        }
      ],
      "shippingAddress": {
        "fullName": "Juan Pérez",
        "streetAddress": "Calle 123 #45-67",
        "city": "Bogotá",
        "phoneNumber": "+57 300 1234567"
      },
      "paymentResult": {
        "id": "pi_1234567890abcdef",
        "status": "succeeded"
      },
      "totalPrice": 25000,
      "status": "in_preparation",
      "paidAt": "2026-03-04T10:30:00.000Z",
      "createdAt": "2026-03-04T10:15:00.000Z",
      "updatedAt": "2026-03-04T11:00:00.000Z"
    }
  ]
}

​
Update Order Status

Update the status of an order. Triggers automated email notifications and invoice generation based on the new status.

​
Authentication

Requires Clerk authentication with admin role.

​
Path Parameters

​
orderId
string
required
MongoDB ObjectId of the order to update

​
Request

​
status
string
required
New order status. Must be one of:
  • pending - Order created but not paid
  • paid - Payment received (triggers invoice generation)
  • in_preparation - Order is being prepared
  • ready - Order ready for pickup/delivery
  • delivered - Order delivered to customer
  • canceled - Order canceled
  • rejected - Order rejected

​
Response

​
message
string
Success message
​
order
object
The updated order object with populated user and product data

​
Automated Actions

When the status changes, the following automated actions occur:

​
Status: paid

  • Sets paidAt timestamp if not already set
  • Generates PDF invoice using generateInvoicePDF()
  • Generates CSV invoice using generateInvoiceCSV()
  • Sends invoice emails to customer and admin via sendInvoiceEmails()
  • Invoice number format: FV-{YEAR}-{ORDER_ID_SUFFIX}
  • Payment method inferred from paymentResult.id prefix:
    • pi_ = Stripe
    • transfer_ = Transferencia

​
Status: delivered

  • Sets deliveredAt timestamp if not already set
  • Sends status update emails to customer and admin

​
All Other Status Changes

  • Sends status update emails to customer (via sendOrderUpdatedClientEmail()) and admin (via sendOrderUpdatedAdminEmail())
  • Respects user’s emailNotifications preference
curl -X PATCH https://api.example.com/api/admin/orders/507f1f77bcf86cd799439011/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_preparation"
  }'

{
  "message": "Order status updated successfully",
  "order": {
    "_id": "507f1f77bcf86cd799439011",
    "user": {
      "_id": "507f191e810c19729de860ea",
      "name": "Juan Pérez",
      "email": "[email protected]",
      "emailNotifications": true
    },
    "clerkId": "user_2abcdefghijklmnop",
    "orderItems": [
      {
        "product": {
          "_id": "507f1f77bcf86cd799439012",
          "name": "Empanada de Carne",
          "price": 5000
        },
        "name": "Empanada de Carne",
        "price": 5000,
        "quantity": 3
      }
    ],
    "shippingAddress": {
      "fullName": "Juan Pérez",
      "streetAddress": "Calle 123 #45-67",
      "city": "Bogotá",
      "phoneNumber": "+57 300 1234567"
    },
    "paymentResult": {
      "id": "pi_1234567890abcdef",
      "status": "succeeded"
    },
    "totalPrice": 25000,
    "status": "in_preparation",
    "paidAt": "2026-03-04T10:30:00.000Z",
    "createdAt": "2026-03-04T10:15:00.000Z",
    "updatedAt": "2026-03-04T11:00:00.000Z"
  }
}

​
Error Responses

{
  "message": "Invalid status"
}

​
Get Dashboard Statistics

Retrieve aggregated statistics for the admin dashboard including total revenue, orders, customers, and products.

​
Authentication

Requires Clerk authentication with admin role.

​
Response

​
totalRevenue
number
required
Total revenue from all orders (sum of all order totalPrice fields)
​
totalOrders
number
required
Total number of orders in the system
​
totalCustomers
number
required
Total number of registered users
​
totalProducts
number
required
Total number of products in the catalog

​
Example Request

curl -X GET https://api.donpalitojr.com/api/admin/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "totalRevenue": 15750000,
  "totalOrders": 342,
  "totalCustomers": 156,
  "totalProducts": 48
}
The totalRevenue is calculated by aggregating the totalPrice field from all orders, regardless of order status. This includes pending, paid, and delivered orders.
Use this endpoint to populate dashboard cards and metrics displays in the admin panel.

Build docs developers (and LLMs) love

Get started for freeTalk to us