POST /api/orders
Creates a new order for the authenticated user. Only one pending order is allowed per user at a time.
Authentication
Requires JWT authentication token in the Authorization header.
Request Body
Array of products to orderMongoDB ObjectId of the product
Quantity to order (minimum: 1)
Product color variant (optional)
Response
Indicates if the order was created successfully
The created order objectHuman-readable order ID (format: #TRX-)
Array of ordered products with details
Sum of all product prices
TRC-20 network fee (-0.01 TRX)
Total amount to pay (subtotal + networkFee)
Order status (always ‘pending’ for new orders)
TRC-20 wallet address where payment should be sent
ISO 8601 timestamp of order creation
Order Status Flow
When created, orders start in the pending state. The possible states are:
- pending - Order created, awaiting payment
- completed - Payment confirmed and order fulfilled
- failed - Payment transaction failed
- cancelled - Order cancelled by user or system
- refunded - Payment refunded to user
Error Responses
400 Bad Request
{
"error": "Products are required"
}
{
"error": "You have a pending order. Please complete or cancel it first.",
"code": "PENDING_ORDER_EXISTS",
"pendingOrderId": "507f1f77bcf86cd799439011"
}
{
"error": "Product 507f1f77bcf86cd799439011 not found"
}
{
"error": "Insufficient stock for iPhone 14 Pro"
}
{
"error": "Merchant wallet not configured"
}
Example Request
curl -X POST https://api.cryptoshop.com/api/orders \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"products": [
{
"productId": "507f1f77bcf86cd799439011",
"quantity": 1,
"color": "black"
},
{
"productId": "507f191e810c19729de860ea",
"quantity": 2
}
]
}'
Example Response
{
"success": true,
"message": "Order created successfully",
"order": {
"_id": "507f1f77bcf86cd799439011",
"orderId": "#TRX-1",
"products": [
{
"productId": "507f1f77bcf86cd799439011",
"name": "iPhone 14 Pro",
"price": 999,
"quantity": 1,
"color": "black"
},
{
"productId": "507f191e810c19729de860ea",
"name": "AirPods Pro",
"price": 249,
"quantity": 2,
"color": null
}
],
"subtotal": 1497,
"networkFee": -0.01,
"total": 1496.99,
"status": "pending",
"merchantAddress": "TRC20AddressHere123456789",
"createdAt": "2026-03-04T10:30:00.000Z"
}
}
Important Notes
- Users can only have one pending order at a time
- Product stock is validated before order creation
- The network fee is fixed at -0.01 TRX
- The merchant address is determined from the admin user’s wallet or environment variable
- User must have a configured wallet to create orders