> ## Documentation Index
> Fetch the complete documentation index at: https://help.bodharouteplanner.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Order

> Push a new order into the Bodha inbox.

Create an order that enters your Bodha orders inbox. If coordinates are
provided, it's marked `ready` for planning. Otherwise it enters `needs_review`
for manual geocoding in the dashboard.

This endpoint fires the **`order.created`** webhook event.

## Required fields

**location** `object` *required*

**properties**

**address** `string` *required*

The delivery address.

**latitude** `number`

If provided with longitude, the order is marked `ready`.

**longitude** `number`

**city** `string`

**state** `string`

## Optional fields

**externalOrderId** `string`

Your system's unique order ID. Used as an idempotency key — sending the same
ID twice returns a `409 Conflict`.

**externalOrderNumber** `string`

Human-facing order number shown to dispatchers (e.g. `"#1043"`).

**recipient** `object`

**properties**

**fullName** `string`

**email** `string`

**phone** `string`

**promise** `object`

Delivery promise to the customer.

**properties**

**type** `string` (default: none)

`none`, `on` (specific date), `by` (deadline), `between` (date range), or `weekdays`.

**date** `string`

`YYYY-MM-DD` — the target date for `on`/`by`, or the start of a `between` range.

**endDate** `string`

End date for `between` ranges.

**weekdays** `integer[]`

For `weekdays` type. 0 = Sunday, 6 = Saturday.

**timeWindow** `object`

Intra-day delivery slot.

**properties**

**startTime** `string`

HH:mm format

**endTime** `string`

HH:mm format

**priority** `string` (default: normal)

`normal` or `urgent`.

**items** `object[]`

Line items on this order.

**item properties**

**sku** `string`

**name** `string`

**quantity** `integer`

**parcels** `object`

Parcel dimensions for capacity planning.

**properties**

**count** `integer`

**label** `string`

**weightKg** `number`

**volumeM3** `number`

**orderValue** `number`

Monetary value of the order.

**currency** `string`

ISO 4217 currency code (e.g. `USD`, `GBP`).

**notes** `string`

**deliveryInstructions** `string`

Shown to the driver at the stop.

**tags** `string[]`

**customProperties** `object`

Arbitrary key-value pairs passed through to the stop.

```bash cURL theme={null}
curl -X POST https://api.bodha.run/api/v1/orders \
     -H "X-API-Key: bk_live_..." \
     -H "Content-Type: application/json" \
     -d '{
       "externalOrderId": "ORD-2026-1043",
       "externalOrderNumber": "#1043",
       "recipient": {
         "fullName": "Jane Smith",
         "phone": "+14155551234"
       },
       "location": {
         "address": "456 Oak Ave, San Francisco, CA 94102",
         "latitude": 37.7751,
         "longitude": -122.4193
       },
       "promise": {
         "type": "by",
         "date": "2026-11-01"
       },
       "timeWindow": {
         "startTime": "09:00",
         "endTime": "12:00"
       },
       "items": [
         { "name": "Widget A", "quantity": 2 }
       ],
       "notes": "Leave at side gate"
     }'
```

```javascript Node.js theme={null}
const res = await fetch('https://api.bodha.run/api/v1/orders', {
  method: 'POST',
  headers: {
    'X-API-Key': 'bk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalOrderId: 'ORD-2026-1043',
    recipient: { fullName: 'Jane Smith' },
    location: {
      address: '456 Oak Ave, San Francisco, CA 94102',
      latitude: 37.7751,
      longitude: -122.4193,
    },
  }),
});
const { data } = await res.json();
```

```json 201 theme={null}
{
  "data": {
    "id": "665f1a2b3c4d5e6f7a8b9c0f",
    "source": "api",
    "externalOrderId": "ORD-2026-1043",
    "externalOrderNumber": "#1043",
    "status": "ready",
    "recipient": {
      "fullName": "Jane Smith",
      "phone": "+14155551234"
    },
    "location": {
      "address": "456 Oak Ave, San Francisco, CA 94102",
      "latitude": 37.7751,
      "longitude": -122.4193
    },
    "promise": { "type": "by", "date": "2026-11-01" },
    "priority": "normal",
    "items": [{ "name": "Widget A", "quantity": 2 }],
    "tags": [],
    "customProperties": {},
    "routeId": null,
    "stopId": null,
    "createdAt": "2026-10-28T10:30:00.000Z",
    "updatedAt": "2026-10-28T10:30:00.000Z"
  }
}
```


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