POST /api/orders/ — Create Order from Cart or Items

When a user is ready to check out, POST to this endpoint to create a new order in the pending state. You may supply an explicit items array (useful when the frontend manages cart state locally) or omit it to have the server pull items directly from the user’s MongoDB cart. Either way, stock is decremented immediately and a branded HTML confirmation email is sent to the shipping address. The order expires in 5 minutes; if payment is not completed within that window the order is automatically cancelled and stock is restored.

Endpoint

POST /api/orders/

Authentication

A valid JWT Bearer token is required in the Authorization header. Returns 401 if the token is missing or invalid.

Request Body

items

array

An array of line-item objects to purchase. When provided, the server uses these items instead of the user’s cart stored in MongoDB. Each element must include the fields below. If omitted or empty, items are loaded from the authenticated user’s cart.

Show Item object fields

product_slug

string

required

URL slug that uniquely identifies the product (e.g. "urban-cargo-pants").

product_name

string

required

Human-readable product name for display and email receipts.

quantity

integer

required

Number of units. Defaults to 1 if omitted.

price_paid

number

required

Unit price in COP at the moment of purchase.

selected_size

string

Size variant string (e.g. "M", "XL").

selected_color

string

Color variant string (e.g. "Negro").

shipping_address

object

required

Destination and contact information for the order.

Show Shipping address fields

string

required

Contact email. Also used as the recipient address for the confirmation email.

name

string

required

Full name of the recipient.

phone

string

required

Contact phone number.

address

string

required

Street address, apartment, etc.

city

string

required

City name.

department

string

required

Colombian department (state/province equivalent).

country

string

Defaults to "Colombia" if omitted.

notes

string

Free-text delivery instructions or comments. Included in the confirmation email when present.

Behavior

Item resolution — If items is a non-empty array, those items are used verbatim. Otherwise the server fetches the user’s Cart document from MongoDB. A 400 is returned if the cart is missing or empty.
Order creation — A new Order document is saved with status: "pending" and expires_at set to 5 minutes from now.
Stock decrement — For each line item the matching Product is located by product_slug. If stock_by_variant contains the key "<size>|<color>", that variant’s stock is decremented. Otherwise, the product’s general stock field is decremented. Stock floor is 0.
Cart clear — If the DB cart was used (no items supplied in the body), the cart is emptied after the order is created.
Confirmation email — A styled HTML email is sent to shipping_address.email with the order number, itemised receipt, totals, and shipping address.

The order expires in 5 minutes (expires_at). Your frontend should call POST /api/payments/create-payment-intent/ and complete Stripe checkout before this window closes, or the order will transition to cancelled on the next read.

Request Example

{
  "items": [
    {
      "product_slug": "urban-cargo-pants",
      "product_name": "Urban Cargo Pants",
      "quantity": 1,
      "price_paid": 189000,
      "selected_size": "M",
      "selected_color": "Negro"
    }
  ],
  "shipping_address": {
    "email": "cliente@ejemplo.com",
    "name": "Juan Pérez",
    "phone": "3001234567",
    "address": "Calle 80 # 45-12 Apto 301",
    "city": "Bogotá",
    "department": "Cundinamarca",
    "country": "Colombia"
  },
  "notes": "Dejar en portería si no hay nadie."
}

curl -X POST https://api.urbanstore.co/api/orders/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_slug": "urban-cargo-pants",
        "product_name": "Urban Cargo Pants",
        "quantity": 1,
        "price_paid": 189000,
        "selected_size": "M",
        "selected_color": "Negro"
      }
    ],
    "shipping_address": {
      "email": "cliente@ejemplo.com",
      "name": "Juan Pérez",
      "phone": "3001234567",
      "address": "Calle 80 # 45-12 Apto 301",
      "city": "Bogotá",
      "department": "Cundinamarca",
      "country": "Colombia"
    }
  }'

Response — 201 Created

{
  "id": "664f1a2b3c4d5e6f7a8b9c0d",
  "order_number": "ORD-20240522153045-472",
  "user_id": "cliente@ejemplo.com",
  "items": [
    {
      "product_slug": "urban-cargo-pants",
      "product_name": "Urban Cargo Pants",
      "quantity": 1,
      "size": "M",
      "color": "Negro",
      "price_paid": 189000,
      "subtotal": 189000
    }
  ],
  "subtotal": 189000,
  "tax": 0,
  "shipping": 0,
  "total": 189000,
  "status": "pending",
  "shipping_address": {
    "email": "cliente@ejemplo.com",
    "name": "Juan Pérez",
    "phone": "3001234567",
    "address": "Calle 80 # 45-12 Apto 301",
    "city": "Bogotá",
    "department": "Cundinamarca",
    "country": "Colombia"
  },
  "notes": "Dejar en portería si no hay nadie.",
  "created_at": "2024-05-22T15:30:45.123456+00:00",
  "expires_at": "2024-05-22T15:35:45.123456+00:00",
  "paid_at": null
}

Error Responses

Status	Condition
`401 Unauthorized`	Token missing, malformed, or expired
`400 Bad Request`	`shipping_address` not provided
`400 Bad Request`	No `items` in the body and the user’s cart is empty or does not exist

Users

Products & Cart

Orders & Payments

Analytics

POST /api/orders/ — Create Order from Cart or Items

Endpoint

Authentication

Request Body

Behavior

Request Example

Response — 201 Created

Error Responses

Build docs developers (and LLMs) love

Users

Products & Cart

Orders & Payments

Analytics

Documentation Index

​Endpoint

​Authentication

​Request Body

​Behavior

​Request Example

​Response — 201 Created

​Error Responses

Build docs developers (and LLMs) love

Endpoint

Authentication

Request Body

Behavior

Request Example

Response — 201 Created

Error Responses