Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ALEJ4NDRO2025/urban-store/llms.txt

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

This admin-only endpoint moves an order through its lifecycle. Transitioning to cancelled from any state other than pending or cancelled triggers automatic inventory restoration: each item’s stock is incremented back (using the stock_by_variant key when available, falling back to general stock). Setting status to paid for the first time also records a paid_at timestamp.

​
Endpoint

PATCH /api/orders/{order_id}/status/

​
Authentication

Bearer token required with is_admin: true in the JWT payload. Returns 403 if the user is not an admin.

​
Path Parameter

​
order_id
string
required
The MongoDB ObjectId of the order to update (24-character hex string).

​
Request Body

​
status
string
required
The new status value. Must be one of the valid states listed below.

​
Valid Status Values

StatusDescription
pendingAwaiting payment. Default state at order creation.
paidPayment confirmed. Sets paid_at on first transition.
pending_shipmentPayment received; order is queued for dispatch.
shippedOrder handed to carrier / delivered.
cancelledOrder cancelled. Restores stock if previously beyond pending.
Stock restoration only fires when transitioning to cancelled from a state that is not pending or cancelled. Cancelling a pending order does not restore stock because stock was already decremented at order creation; those orders are cleaned up by the passive expiry mechanism instead.

​
Behavior Details

​
Stock Restoration (on cancel)

When new_status == 'cancelled' and order.status not in ['pending', 'cancelled']:
  1. For each item in the order, the matching Product is located by product_slug.
  2. If product.stock_by_variant contains the key "<size>|<color>", that variant’s quantity is incremented by item.quantity.
  3. Otherwise, the product’s general stock field is incremented by item.quantity.
If new_status == 'paid' and order.paid_at is currently null, paid_at is set to the current UTC time.

​
Request Example

{
  "status": "paid"
}

curl -X PATCH https://api.urbanstore.co/api/orders/664f1a2b3c4d5e6f7a8b9c0d/status/ \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid"}'

​
Response — 200 OK

Returns the full updated order object (same shape as GET /api/orders/{order_id}/). 
{
  "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": "paid",
  "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": "",
  "created_at": "2024-05-22T15:30:45.123456+00:00",
  "expires_at": "2024-05-22T15:35:45.123456+00:00",
  "paid_at": "2024-05-22T15:33:12.000000+00:00"
}

​
Error Responses

StatusCondition
400 Bad Requeststatus value is not one of the five valid states
403 ForbiddenCaller is not an admin
404 Not FoundNo order found with the given order_id

Build docs developers (and LLMs) love

Get started for freeTalk to us