Admin customers

Browse customers and drill into a single customer's order history. 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.

An admin only sees customers who have ordered in their assigned cities.

Endpoints

Method URI Access Description
GET /admin/customers Admin Paginated customer list with spend totals
GET /admin/customers/{customerId} Admin Customer profile, totals & recent orders

GET /admin/customers

Page-paginated customer list (newest first). See Pagination → page-based.

Query

Field Type Required Rules
is_active boolean no filter by the user's active flag
min_spent number no ≥ 0; approximate minimum spend in USD
max_spent number no ≥ 0; approximate maximum spend in USD
q string no ≤ 80 chars; matches name or phone
limit integer no 1–100, default 25
page integer no ≥ 1, default 1

min_spent / max_spent are approximate, not an exact order total.

Response 200

{
  "items": [
    {
      "id": 1,
      "name": "Ana MartĂ­nez",
      "phone": "+584241000001",
      "email": "ana@example.com",
      "is_active": true,
      "total_orders": 12,
      "total_liters_ordered": 36000,
      "total_solidary_usd": 4.2,
      "created_at": "2026-06-01T09:00:00+00:00"
    }
  ],
  "meta": { "total": 137, "per_page": 25, "current_page": 1, "last_page": 6 }
}

GET /admin/customers/{customerId}

Customer profile, lifetime totals, and a page of their orders (newest first).

Query

Field Type Required Rules
limit integer no 1–100, default 10
page integer no ≥ 1, default 1

Response 200

{
  "customer": {
    "id": 1,
    "name": "Ana MartĂ­nez",
    "phone": "+584241000001",
    "email": "ana@example.com",
    "is_active": true,
    "created_at": "2026-06-01T09:00:00+00:00",
    "updated_at": "2026-06-28T18:00:00+00:00"
  },
  "totals": {
    "total_orders": 12,
    "total_liters_ordered": 36000,
    "total_spent_usd": 4.2
  },
  "orders": [
    {
      "id": 42,
      "status": "DELIVERED",
      "location_from": { "lat": 10.487, "lng": -66.88, "text": "Av. Principal" },
      "location_to": { "lat": null, "lng": null, "text": null },
      "liters": 5000,
      "price_usd": 20.2,
      "driver": { "id": 3, "name": "Carlos RodrĂ­guez", "phone": "+584241001001" },
      "created_at": "2026-06-26T12:00:00+00:00",
      "completed_at": "2026-06-26T12:40:00+00:00"
    }
  ],
  "meta": { "total": 12, "per_page": 10, "current_page": 1, "last_page": 2 }
}

driver is null for orders that were never assigned. location_to is currently always null-valued.

Errors

Status Body When
404 { "error": "CustomerNotFound" } No customer (client profile) with that id