Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/peLuis123/crypto-shop-backend/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
products
array
required
Array of products to order
​
productId
string
required
MongoDB ObjectId of the product
​
quantity
number
required
Quantity to order (minimum: 1)
​
color
string
Product color variant (optional)

​
Response

​
success
boolean
Indicates if the order was created successfully
​
message
string
Success message
​
order
object
The created order object
​
_id
string
Order MongoDB ObjectId
​
orderId
string
Human-readable order ID (format: #TRX-)
​
products
array
Array of ordered products with details
​
subtotal
number
Sum of all product prices
​
networkFee
number
TRC-20 network fee (-0.01 TRX)
​
total
number
Total amount to pay (subtotal + networkFee)
​
status
string
Order status (always ‘pending’ for new orders)
​
merchantAddress
string
TRC-20 wallet address where payment should be sent
​
createdAt
string
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"
}
409 Conflict - User has an existing pending order 
{
  "error": "You have a pending order. Please complete or cancel it first.",
  "code": "PENDING_ORDER_EXISTS",
  "pendingOrderId": "507f1f77bcf86cd799439011"
}
404 Not Found - Product not found 
{
  "error": "Product 507f1f77bcf86cd799439011 not found"
}
400 Bad Request - Insufficient stock 
{
  "error": "Insufficient stock for iPhone 14 Pro"
}
500 Internal Server Error - Merchant wallet not configured 
{
  "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

Build docs developers (and LLMs) love

Get started for freeTalk to us