Skip to main content

​
POST /api/create-order

Creates a new order, reserves inventory, and generates a shipment with the logistics provider (Venndelo).
This endpoint performs multiple critical operations: stock reservation, database persistence, and logistics API calls. Ensure all required fields are provided to avoid partial failures.

​
Request Body

​
billing_info
object
required
Customer billing information
​
billing_info.first_name
string
required
First name
​
billing_info.last_name
string
required
Last name
​
billing_info.email
string
required
Email address
​
billing_info.phone
string
required
Phone number
​
billing_info.identification_type
string
required
ID type (e.g., “CC”, “NIT”)
​
billing_info.identification
string
required
Identification number
​
shipping_info
object
required
Shipping destination information
​
shipping_info.first_name
string
required
Recipient first name
​
shipping_info.last_name
string
required
Recipient last name
​
shipping_info.address_1
string
required
Delivery address
​
shipping_info.city_code
string
required
DANE city code
​
shipping_info.subdivision_code
string
required
DANE department code
​
shipping_info.country_code
string
required
Country code (e.g., “CO”)
​
shipping_info.phone
string
required
Recipient phone
​
shipping_info.postal_code
string
Postal code (optional)
​
line_items
array
required
Array of products to order
​
line_items[].sku
string
required
Product SKU
​
line_items[].name
string
required
Product name
​
line_items[].unit_price
number
required
Unit price
​
line_items[].quantity
number
required
Quantity
​
line_items[].weight
number
required
Weight in kilograms
​
line_items[].weight_unit
string
required
Weight unit (must be “KG”)
​
line_items[].dimensions_unit
string
required
Dimensions unit (must be “CM”)
​
line_items[].height
number
required
Height in centimeters
​
line_items[].width
number
required
Width in centimeters
​
line_items[].length
number
required
Length in centimeters
​
line_items[].type
string
Item type: “STANDARD” or “VIRTUAL” (default: “STANDARD”)
​
payment_method_code
string
required
Payment method: “COD” (cash on delivery) or “EXTERNAL_PAYMENT” (Wompi)
​
external_order_id
string
required
External order reference ID
​
pickup_info
object
Optional pickup location (if different from default warehouse)
​
discounts
array
Optional discounts array

​
Response

​
success
boolean
Indicates if order was created successfully
​
order
object
Order details
​
order.db_id
string
Internal database UUID
​
order.readable_id
number
Human-readable order number (e.g., 1050)
​
order.external_id
string
Venndelo shipment ID
​
order.total
number
Total amount including shipping
​
order.shipping_cost
number
Shipping cost
​
order.carrier_name
string
Logistics carrier name
​
order.trackingNumber
string
Tracking number (if available)

​
Example Request

curl -X POST http://localhost:3001/api/create-order \
  -H "Content-Type: application/json" \
  -d '{
    "billing_info": {
      "first_name": "Ana",
      "last_name": "García",
      "email": "[email protected]",
      "phone": "+573001234567",
      "identification_type": "CC",
      "identification": "1234567890"
    },
    "shipping_info": {
      "first_name": "Ana",
      "last_name": "García",
      "address_1": "Calle 123 #45-67, Apto 301",
      "city_code": "11001",
      "subdivision_code": "11",
      "country_code": "CO",
      "phone": "+573001234567",
      "postal_code": "110111"
    },
    "line_items": [
      {
        "sku": "SERUM-VITAMIN-C",
        "name": "Serum Vitamina C",
        "unit_price": 89000,
        "quantity": 1,
        "weight": 0.15,
        "weight_unit": "KG",
        "dimensions_unit": "CM",
        "height": 12,
        "width": 4,
        "length": 4,
        "type": "STANDARD"
      }
    ],
    "payment_method_code": "COD",
    "external_order_id": "WEB-20260304-001"
  }'

​
Example Response

{
  "success": true,
  "order": {
    "db_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "readable_id": 1050,
    "external_id": "VND-2026-001234",
    "total": 104500,
    "shipping_cost": 15500,
    "carrier_name": "Coordinadora",
    "trackingNumber": null
  }
}

​
Order Processing Flow

  1. Validation: Request data is validated using Zod schema
  2. Stock Reservation: Inventory is reserved for all line items
  3. Database Creation: Order is created with status PENDING
  4. Logistics Integration: Shipment is created with Venndelo
  5. Confirmation: Order is updated with external ID and shipping cost
  6. Email Notification: Confirmation email sent (COD orders only)

​
Payment Methods

​
COD (Cash on Delivery)

When payment_method_code: "COD":
  • Stock is immediately confirmed (deducted from inventory)
  • Order confirmation email is sent immediately
  • Payment collected upon delivery

​
EXTERNAL_PAYMENT (Wompi)

When payment_method_code: "EXTERNAL_PAYMENT":
  • Stock is reserved but not confirmed
  • Stock confirmed after webhook payment confirmation
  • Email sent after payment confirmation

​
Error Responses

​
400 Bad Request - Invalid Data

{
  "error": "Datos inválidos",
  "details": {
    "billing_info": {
      "email": {
        "_errors": ["Invalid email"]
      }
    }
  }
}

​
409 Conflict - Insufficient Stock

{
  "error": "Producto SERUM-VITAMIN-C no tiene stock suficiente. Disponible: 0, Solicitado: 1"
}

​
500 Internal Server Error - Database Error

{
  "error": "Error guardando orden en base de datos"
}

​
502 Bad Gateway - Logistics Error

{
  "error": "Error creando envío con transportadora",
  "details": "Venndelo API timeout"
}

​
Rollback Mechanism

The endpoint implements automatic rollback on failures:
  • If logistics creation fails, the order is cancelled and stock is released
  • If database save fails, stock reservation is released
  • All operations are atomic to prevent inconsistent states

Build docs developers (and LLMs) love

Get started for freeTalk to us