> ## 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.

# Cancel order

> Cancel an order and refund the cost to your Business wallet when it was wallet-paid.

Cancels an order and, if it was paid from your Business wallet, refunds the cost to that wallet.

Requires scope: `orders:write`

<Info>
  An order can only be cancelled while its `status` is one of:

  * `PENDING`
  * `ASSIGNED`
  * `ACCEPTED`
  * `START_TRIP`

  Any other status (for example `HEADING_TO_PICKUP`, `PICKED_UP`, `HEADING_TO_DELIVERY`, or `DELIVERED`) is rejected with `400`.

  Only single-order cancellation is supported — there is no bulk cancel.
</Info>

See [Shipment statuses](/concepts/shipment-statuses) for the full lifecycle.

## Headers

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

<ParamField header="Content-Type" type="string">
  `application/json` when sending a body.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>
  MongoDB document id of the order (not the `order_id` display code). Same id as [Get order](/orders/get-order).
</ParamField>

## Body

<ParamField body="reason" type="string">
  Optional cancel reason (max 500 characters).
</ParamField>

## Response

<ResponseField name="message" type="string">
  Success message.
</ResponseField>

<ResponseField name="order_id" type="string">
  Human-readable order code.
</ResponseField>

<ResponseField name="status" type="string">
  Always `CANCELLED` on success.
</ResponseField>

<ResponseField name="cancel" type="boolean">
  Always `true` on success.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "$RUN_BASE_URL/business/orders/6a7c75f801df3fbb7fad0c58/cancel" \
    -H "Authorization: Bearer $RUN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "reason": "Customer changed address" }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    `${process.env.RUN_BASE_URL}/business/orders/6a7c75f801df3fbb7fad0c58/cancel`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.RUN_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ reason: 'Customer changed address' }),
    },
  );
  const result = await res.json();
  ```

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

  res = requests.post(
      f"{os.environ['RUN_BASE_URL']}/business/orders/6a7c75f801df3fbb7fad0c58/cancel",
      headers={
          "Authorization": f"Bearer {os.environ['RUN_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={"reason": "Customer changed address"},
  )
  result = res.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init(getenv('RUN_BASE_URL') . '/business/orders/6a7c75f801df3fbb7fad0c58/cancel');
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      'Authorization: Bearer ' . getenv('RUN_API_KEY'),
      'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
      'reason' => 'Customer changed address',
    ]),
  ]);
  $result = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```

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

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

  func main() {
    body := []byte(`{"reason":"Customer changed address"}`)
    req, _ := http.NewRequest(
      "POST",
      os.Getenv("RUN_BASE_URL")+"/business/orders/6a7c75f801df3fbb7fad0c58/cancel",
      bytes.NewReader(body),
    )
    req.Header.Set("Authorization", "Bearer "+os.Getenv("RUN_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    res, err := http.DefaultClient.Do(req)
    if err != nil {
      panic(err)
    }
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "message": "Dispatch cancelled successfully",
    "order_id": "RUN-A1B2C3D4",
    "status": "CANCELLED",
    "cancel": true
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "timestamp": "2026-08-12T15:18:51.396Z",
    "path": "/api/v2/business/orders/6a7c75f801df3fbb7fad0c58/cancel",
    "message": "Order cannot be cancelled in its current status"
  }
  ```

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

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

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "timestamp": "2026-08-12T15:18:51.396Z",
    "path": "/api/v2/business/orders/6a7c75f801df3fbb7fad0c58/cancel",
    "message": "Order not found"
  }
  ```
</ResponseExample>


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