> ## Documentation Index
> Fetch the complete documentation index at: https://run-deliverys.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List orders

> List orders for your Business with optional filters.

List orders for your Business.

Requires scope: `orders:read`

Your API key can only list orders that belong to your Business. Use [Get order](/orders/get-order) when you need the full `timeline`.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer API key (`Bearer <api_key>`).
</ParamField>

## Query parameters

<ParamField query="page" type="number">
  Page number (default `1`).
</ParamField>

<ParamField query="limit" type="number">
  Page size (default `10`).
</ParamField>

<ParamField query="search" type="string">
  Free-text search (order code, recipient name, phone).
</ParamField>

<ParamField query="status" type="string">
  Filter by shipment status.
</ParamField>

<ParamField query="sortBy" type="string">
  Sort field: `NEWEST`, `OLDEST`, `PRICE_LOW_TO_HIGH`, `PRICE_HIGH_TO_LOW`, `DISTANCE_LOW_TO_HIGH`, `DISTANCE_HIGH_TO_LOW`.
</ParamField>

<ParamField query="dateFrom" type="string">
  ISO start date on `createdAt`.
</ParamField>

<ParamField query="dateTo" type="string">
  ISO end date on `createdAt`.
</ParamField>

## Response

<ResponseField name="orders" type="array">
  Page of orders (list payload omits `timeline`).
</ResponseField>

<ResponseField name="total" type="number">
  Total matching orders.
</ResponseField>

<ResponseField name="page" type="number">
  Current page.
</ResponseField>

<ResponseField name="limit" type="number">
  Page size.
</ResponseField>

<ResponseField name="pages" type="number">
  Total pages.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "$RUN_BASE_URL/business/orders?limit=20&page=1" \
    -H "Authorization: Bearer $RUN_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ limit: '20', page: '1' });
  const res = await fetch(
    `${process.env.RUN_BASE_URL}/business/orders?${params}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.RUN_API_KEY}`,
      },
    },
  );
  const data = await res.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  res = requests.get(
      f"{os.environ['RUN_BASE_URL']}/business/orders",
      params={"limit": 20, "page": 1},
      headers={"Authorization": f"Bearer {os.environ['RUN_API_KEY']}"},
  )
  data = res.json()
  ```

  ```php PHP theme={null}
  <?php
  $query = http_build_query(['limit' => 20, 'page' => 1]);
  $ch = curl_init(getenv('RUN_BASE_URL') . "/business/orders?{$query}");
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      'Authorization: Bearer ' . getenv('RUN_API_KEY'),
    ],
  ]);
  $data = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "net/http"
    "os"
  )

  func main() {
    req, _ := http.NewRequest(
      "GET",
      os.Getenv("RUN_BASE_URL")+"/business/orders?limit=20&page=1",
      nil,
    )
    req.Header.Set("Authorization", "Bearer "+os.Getenv("RUN_API_KEY"))
    res, err := http.DefaultClient.Do(req)
    if err != nil {
      panic(err)
    }
    defer res.Body.Close()
    body, _ := io.ReadAll(res.Body)
    fmt.Println(string(body))
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "orders": [
      {
        "_id": "6a7c75f801df3fbb7fad0c58",
        "order_id": "RUN-A1B2C3D4",
        "status": "PENDING",
        "price": 5300,
        "distance": 7.54,
        "sender_name": "Acme Stores",
        "sender_phone": "+2348011111111",
        "pickup_locations": [
          {
            "pickup": {
              "address": "12 Admiralty Way, Lekki, Lagos",
              "state": "Lagos"
            },
            "dropoff": {
              "address": "15 Admiralty Way, Lekki, Lagos",
              "state": "Lagos",
              "recipient_name": "Adewale Johnson",
              "recipient_phone_number": "+2348022222222"
            },
            "item": {
              "name": "Shoes",
              "weight": 5,
              "quantity": 1
            },
            "status": "PENDING"
          }
        ],
        "createdAt": "2026-08-12T10:15:00.000Z",
        "updatedAt": "2026-08-12T10:15:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 20,
    "pages": 3
  }
  ```

  ```json 401 theme={null}
  {
    "statusCode": 401,
    "timestamp": "2026-08-12T15:18:51.396Z",
    "path": "/api/v2/business/orders",
    "message": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "statusCode": 403,
    "timestamp": "2026-08-12T15:18:51.396Z",
    "path": "/api/v2/business/orders",
    "message": "Insufficient API key scope"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.