Admin orders

Browse live and archived orders, export them, read full detail, force status changes, and refund a client over Pago Móvil. Paths are relative to the /api/v1 prefix; these are back-office endpoints requiring an admin token.

Requires an admin bearer token (see Admin auth). Admin only.

See Common errors and the order lifecycle.

Admins see the full order record with all money fields.

Endpoints

GET /admin/orders

Cursor-paginated live orders (archived excluded), newest first. See Pagination → cursor-based.

Query

Response 200

{
  "items": [
    {
      "id": 42,
      "status": "IN_PROGRESS",
      "client": { "id": 1, "name": "Ana Martínez", "phone": "+584241000001" },
      "driver": { "id": 3, "name": "Carlos Rodríguez", "phone": "+584241001001" },
      "liters": 5000,
      "amount_usd": 20.2,
      "payment_method": "CASH_USD",
      "address": "Av. Principal, Las Mercedes",
      "created_at": "2026-06-26T12:00:00+00:00"
    }
  ],
  "next_cursor": "eyJpZCI6NDF9",
  "has_more": true
}

driver is null for unassigned orders.

GET /admin/orders/export

Streams the filtered orders as a CSV download (Content-Type: text/csv); there is no JSON body. Accepts the same filters as the list except limit/cursor. Columns: ID, Status, Client Name, Driver Name, Liters, Price (USD), Payment Method, Created At, Delivered At, Cancelled At, Cancelled By.

Errors

GET /admin/orders/stats

Status counters over the live (non-archived) set, for the dashboard cards.

Response 200

{
  "active": 13,
  "today": 8,
  "delivered": 30,
  "cancelled_expired": 4,
  "broadcasting": 1,
  "waiting_for_payment": 1,
  "confirmed": 3,
  "in_progress": 5,
  "arrived": 2
}

active covers all non-archived orders; cancelled_expired covers CANCELLED and EXPIRED orders.

GET /admin/orders/archived

Same shape, filters, and cursor pagination as GET /admin/orders, but over archived orders (terminal orders from previous days).

Response 200 — { "items": [ … ], "next_cursor": "…", "has_more": false }.

GET /admin/orders/{orderId}

Full order detail. The order is the complete record (all money fields), plus a timeline and the in-order chat.

billing holds the customer's billing data as it stood when the order was created, or null when the order has none. billing.address is the billing address, unrelated to the order's delivery address.

Response 200

{
  "order": {
    "id": 42,
    "status": "DELIVERED",
    "client_id": 1,
    "driver_id": 3,
    "address": "Av. Principal, Las Mercedes",
    "liters_requested": 5000,
    "actual_liters": 5000,
    "payment_method": "CASH_USD",
    "base_price_usd": 20.0,
    "client_pays_usd": 20.0,
    "aguita_revenue_usd": 3.6,
    "driver_receives_usd": 16.4,
    "solidary_fund_usd": 0.0,
    "delivery_pin": "1234",
    "billing": {
      "entity_type": "JURIDICA",
      "id_number": "J-123456789",
      "name": "Distribuidora Aguas del Valle, C.A.",
      "address": "Av. Libertador, Torre Norte, Piso 3, Caracas",
      "phone": "+58 212 5551234"
    }
  },
  "timeline": [
    { "event": "CREATED", "at": "2026-06-26T12:00:00+00:00" },
    { "event": "CONFIRMED", "at": "2026-06-26T12:05:00+00:00" },
    { "event": "DELIVERED", "at": "2026-06-26T12:40:00+00:00" }
  ],
  "chat": [
    {
      "id": 1,
      "sender_id": 1,
      "sender_role": "client",
      "body": "¿Cuánto falta?",
      "created_at": "2026-06-26T12:20:00+00:00"
    }
  ]
}

A CANCELLED timeline entry also carries by and reason. See Business → money breakdown.

Errors

GET /admin/orders/cancellation-reasons

Admin cancellation-reason catalogue, for the reason dropdown when forcing a CANCELLED status.

Response 200

{ "reasons": [ { "code": "ADMIN_FRAUD", "label": "Sospecha de fraude" } ] }

PATCH /admin/orders/{orderId}/force-status

Forces the order into a new status. Only lifecycle-valid transitions are allowed; terminal states (DELIVERED, CANCELLED, EXPIRED) cannot transition.

Request body

Response 200

{
  "order": {
    "id": 42,
    "status": "DELIVERED",
    "accepted_at": "2026-06-26T12:02:00+00:00",
    "confirmed_at": "2026-06-26T12:05:00+00:00",
    "paid_at": "2026-06-26T12:05:00+00:00",
    "in_progress_at": "2026-06-26T12:10:00+00:00",
    "arrived_at": "2026-06-26T12:35:00+00:00",
    "delivered_at": "2026-06-26T12:40:00+00:00",
    "cancelled_at": null,
    "delivery_pin": "1234",
    "side_effects": { "delivery_pin_generated": true }
  },
  "audit_entry": {
    "from_status": "ARRIVED",
    "to_status": "DELIVERED",
    "reason": "Confirmación manual de entrega",
    "admin_id": 1,
    "created_at": "2026-06-29T12:00:00+00:00"
  }
}

side_effects may include delivery_pin_generated and/or payment_cancelled.

Errors

GET /admin/orders/{orderId}/refund

Returns the ceiling for a refund and the order's refund when one exists. An order has at most one refund.

Response 200

{
  "refundable_usd": 10.1,
  "refund": {
    "id": 7,
    "order_id": 42,
    "kind": "PARTIAL",
    "status": "CONFIRMED",
    "amount_usd": 4,
    "amount_bs": 160,
    "bcv_rate": 40,
    "beneficiary": {
      "name": "María Pérez",
      "id_number": "V12345678",
      "phone": "04125551234",
      "bank_code": "0102"
    },
    "reference": "998877",
    "last_error": null,
    "created_at": "2026-09-12T14:00:00+00:00",
    "confirmed_at": "2026-09-12T14:02:00+00:00"
  },
  "saved_account": {
    "id_number": "V12345678",
    "phone": "04125551234",
    "bank_code": "0102"
  }
}

Errors

POST /admin/orders/{orderId}/refund

Refunds the client over Pago Móvil. The beneficiary's data is required: the platform holds no bank details for clients.

Request body

Response 201 — { "refund": { … } }, same shape as the GET.

Errors