Fleet order ingestion

If you run a fleet on Maxmove, your customers' systems can send orders to you through the API. 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 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.
• 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.
• Optional items, your customer's reference, a requested pickup date and time, and notes.

The API reference 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.

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

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);

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

All other codes are listed in Errors.