# Fleet order ingestion

> For fleets on Maxmove: let your customers' ERP, shop, or e-mail parser push orders straight onto your own dispatch board.

If you run a fleet on Maxmove, your customers' systems can send orders to you through the API. [`POST /v1/fleet/orders`](https://api.maxmove.com/v1/docs#tag/fleet-orders/POST/v1/fleet/orders) pushes an order from your customer's system (ERP, shop, or e-mail parser) straight onto your own dispatch board, without the marketplace.

This is the carrier side of the API. To book Maxmove couriers as a shipper, use [deliveries](https://maxmove.com/en/developers/docs/concepts/deliveries) instead.

## Requirements

- A key of a **fleet workspace**. Keys of business workspaces answer `403 fleet_key_required`.
- A **live key** (`mm_live_…`). Fleet orders always land on your real dispatch board, so there is no test mode for them: test keys answer `403 live_key_required`, both when creating and when reading orders.
- The `fleet_orders:create` permission to create orders, and `fleet_orders:read` to read them. See [Authentication](https://maxmove.com/en/developers/docs/authentication#content-permissions).
- A fleet plan that includes order intake. Otherwise requests answer `403 fleet_orders_not_available`.

## Create an order

An order carries:

- `customer`: your customer who placed the order.
- `pickup` and `dropoff`, and optionally up to 10 `stops`: each with address and coordinates, plus optional `contact` and `instructions` for that place.
- `vehicle_type_id`: an id from [`GET /v1/vehicle-types`](https://api.maxmove.com/v1/docs#tag/vehicle-types/GET/v1/vehicle-types).
- Optional `items`, your customer's `reference`, a requested pickup date and time, and `notes`.

The [API reference](https://api.maxmove.com/v1/docs#tag/fleet-orders/POST/v1/fleet/orders) lists every field with its format.

The `Idempotency-Key` header is required. Use your customer's order id, for example. A retry with the same key answers `201` with the existing order instead of creating a second one. See [Idempotency](https://maxmove.com/en/developers/docs/concepts/idempotency).

```bash cURL
curl -X POST https://api.maxmove.com/v1/fleet/orders \
  -H "x-api-key: $MAXMOVE_FLEET_KEY" -H "content-type: application/json" \
  -H "Idempotency-Key: PO-2026-1187" \
  -d @order.json
```

```ts Node.js
const res = await fetch('https://api.maxmove.com/v1/fleet/orders', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.MAXMOVE_FLEET_KEY!,
    'content-type': 'application/json',
    'Idempotency-Key': 'PO-2026-1187',
  },
  body: JSON.stringify(order),
});
const fleetOrder = await res.json();
console.log(res.status, fleetOrder.id, fleetOrder.status);
```

```python Python
import os
import requests

fleet_order = requests.post(
    "https://api.maxmove.com/v1/fleet/orders",
    headers={
        "x-api-key": os.environ["MAXMOVE_FLEET_KEY"],
        "Idempotency-Key": "PO-2026-1187",
    },
    json=order,
).json()
print(fleet_order["id"], fleet_order["status"])
```

`order` stands for the request body described above.

If you send `items`, Maxmove checks that the vehicle type can carry them and answers `400 vehicle_does_not_fit` when it cannot.

## Read an order

[`GET /v1/fleet/orders/{fleetOrderId}`](https://api.maxmove.com/v1/docs#tag/fleet-orders/GET/v1/fleet/orders/{fleetOrderId}) returns the order as it stands on your dispatch board, with its status, your `reference`, and, when available, a tracking URL.

Fleet orders don't send webhook events. Read the order to check its progress.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 403 | `fleet_key_required` | The key belongs to a business workspace. Use a key of your fleet workspace. |
| 403 | `live_key_required` | The key is a test key. Use a live key. |
| 403 | `fleet_orders_not_available` | Your fleet plan does not include order intake. |
| 403 | `permission_denied` | The key lacks `fleet_orders:create` or `fleet_orders:read`. |
| 400 | `vehicle_does_not_fit` | The vehicle type cannot carry the items. |

All other codes are listed in [Errors](https://maxmove.com/en/developers/docs/concepts/errors).

---

Source: https://maxmove.com/en/developers/docs/fleet/order-ingestion