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

# Place orders

> Place one or more Local orders and debit the Business wallet.

Place one or more Local orders. The body is a JSON array of **1–100** shipments. Run re-quotes, creates dispatches, and debits your Business wallet in one transaction.

Requires scope: `orders:write`

## Headers

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

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

Each array item supports:

<ParamField body="dropoff_address" type="string" required>
  Delivery destination (≥ 5 chars).
</ParamField>

<ParamField body="dropoff_state" type="string" required>
  Delivery state.
</ParamField>

<ParamField body="recipient_name" type="string" required>
  Recipient name.
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  Recipient phone.
</ParamField>

<ParamField body="item_name" type="string" required>
  Item name.
</ParamField>

<ParamField body="weight" type="number" required>
  Weight per unit in kg (0.1–100).
</ParamField>

<ParamField body="quantity" type="number" required>
  Quantity (≥ 1).
</ParamField>

<ParamField body="pickup_address" type="string">
  Defaults to business profile address.
</ParamField>

<ParamField body="pickup_state" type="string">
  Defaults to business profile state.
</ParamField>

<ParamField body="sender_name" type="string">
  Defaults to business name.
</ParamField>

<ParamField body="sender_phone" type="string">
  Defaults to business phone.
</ParamField>

<ParamField body="recipient_email" type="string">
  Optional email.
</ParamField>

<ParamField body="recipient_alternate_phone" type="string">
  Optional alternate phone.
</ParamField>

<ParamField body="item_category" type="string">
  Optional category.
</ParamField>

<ParamField body="item_description" type="string">
  Optional description.
</ParamField>

<ParamField body="item_value" type="number">
  Optional declared value.
</ParamField>

<ParamField body="is_fragile" type="boolean">
  Fragile flag.
</ParamField>

<ParamField body="vehicle_type" type="string">
  `bike`, `bus_van`, or `truck`. Prefer this for rate-card pricing. See [Rate cards](/orders/rate-cards).
</ParamField>

<ParamField body="option_id" type="string">
  Option id from the catalog. Required for `bus_van` / `truck`; omit for bike.
</ParamField>

<ParamField body="pickup_lat" type="number">
  Optional pickup latitude.
</ParamField>

<ParamField body="pickup_lng" type="number">
  Optional pickup longitude.
</ParamField>

<ParamField body="dropoff_lat" type="number">
  Optional drop-off latitude.
</ParamField>

<ParamField body="dropoff_lng" type="number">
  Optional drop-off longitude. If all four lat/lng are set, geocode is skipped.
</ParamField>

## Response

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

<ResponseField name="description" type="string">
  Human-readable result.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code.
</ResponseField>

<ResponseField name="charged_total" type="number">
  Total debited from the Business wallet.
</ResponseField>

<ResponseField name="orders" type="array">
  Created orders with `order_id` and `price`.
</ResponseField>

<Warning>
  **Wallet balance.** Fund your Business wallet from the dashboard before placing orders. Insufficient funds return `400`.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "$RUN_BASE_URL/business/order" \
    -H "Authorization: Bearer $RUN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '[
      {
        "dropoff_address": "24 Allen Avenue, Ikeja, Lagos",
        "dropoff_state": "Lagos",
        "recipient_name": "Adewale Johnson",
        "recipient_phone": "+2348022222222",
        "item_name": "Shoes",
        "weight": 2,
        "quantity": 1,
        "vehicle_type": "bike"
      }
    ]'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(`${process.env.RUN_BASE_URL}/business/order`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RUN_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify([
      {
        dropoff_address: '24 Allen Avenue, Ikeja, Lagos',
        dropoff_state: 'Lagos',
        recipient_name: 'Adewale Johnson',
        recipient_phone: '+2348022222222',
        item_name: 'Shoes',
        weight: 2,
        quantity: 1,
        vehicle_type: 'bike',
      },
    ]),
  });
  const result = await res.json();
  ```

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

  res = requests.post(
      f"{os.environ['RUN_BASE_URL']}/business/order",
      headers={
          "Authorization": f"Bearer {os.environ['RUN_API_KEY']}",
          "Content-Type": "application/json",
      },
      json=[
          {
              "dropoff_address": "24 Allen Avenue, Ikeja, Lagos",
              "dropoff_state": "Lagos",
              "recipient_name": "Adewale Johnson",
              "recipient_phone": "+2348022222222",
              "item_name": "Shoes",
              "weight": 2,
              "quantity": 1,
              "vehicle_type": "bike",
          }
      ],
  )
  result = res.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init(getenv('RUN_BASE_URL') . '/business/order');
  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([
      [
        'dropoff_address' => '24 Allen Avenue, Ikeja, Lagos',
        'dropoff_state' => 'Lagos',
        'recipient_name' => 'Adewale Johnson',
        'recipient_phone' => '+2348022222222',
        'item_name' => 'Shoes',
        'weight' => 2,
        'quantity' => 1,
        'vehicle_type' => 'bike',
      ],
    ]),
  ]);
  $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(`[
      {
        "dropoff_address": "24 Allen Avenue, Ikeja, Lagos",
        "dropoff_state": "Lagos",
        "recipient_name": "Adewale Johnson",
        "recipient_phone": "+2348022222222",
        "item_name": "Shoes",
        "weight": 2,
        "quantity": 1,
        "vehicle_type": "bike"
      }
    ]`)
    req, _ := http.NewRequest(
      "POST",
      os.Getenv("RUN_BASE_URL")+"/business/order",
      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}
  {
    "status": "Success",
    "description": "Order successfully created",
    "currency": "NGN",
    "charged_total": 5300,
    "orders": [
      { "order_id": "RUN-A1B2C3D4", "price": 5300 }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "timestamp": "2026-08-12T15:18:51.396Z",
    "path": "/api/v2/business/orders",
    "message": "Insufficient wallet balance"
  }
  ```

  ```json 400 (validation) theme={null}
  {
    "statusCode": 400,
    "timestamp": "2026-08-12T15:18:51.396Z",
    "path": "/api/v2/business/orders",
    "message": "One or more orders could not be placed"
  }
  ```

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