Plan and approve trips for your own riders

These endpoints are for orders created with delivery_mode: "OUTLET". They optimise the queued orders across your online riders with the same engine as the outlet portal and, by default, assign the trips at once. MINIDROP orders are never touched. All calls need your access token.

Set BASE_URL to the API address you were given. The examples below use $BASE_URL and $ACCESS_TOKEN.

Recommended flow#

POST /api/orders  {..., "delivery_mode": "OUTLET"}     repeat for each orderPOST /api/trips   {}                                   send an Idempotency-Key header<- webhooks: order.updated with status ASSIGNED, then PICKED_UP, DELIVERED ...

Plan trips#

POST /api/trips. Every body field is optional.

Send the optional header Idempotency-Key: <string, max 100 chars>. Reusing a key within 24 hours returns the first response and creates nothing new, so a retry after a timeout is safe.

curl -X POST "$BASE_URL/api/trips" \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: dispatch-2026-10-20-1" \  -d '{}'

Response 201:

{  "success": true,  "data": {    "batch_id": "uuid",    "status": "DISPATCHED",    "is_optimized": true,    "baseline_distance_km": 42.1,    "optimized_distance_km": 27.4,    "km_saved": 14.7,    "trips": [      {        "trip_id": "uuid",        "status": "ASSIGNED",        "distance_km": 13.2,        "delivery_executive": { "id": "uuid", "name": "Ravi", "phone": "+9198..." },        "orders": [          { "order_id": "uuid", "order_number": "MD...", "reference_order_id": "POS-1", "sequence": 0, "status": "ASSIGNED", "track_url": null }        ]      }    ],    "unassigned_orders": [{ "order_id": "uuid", "reason": "UNKNOWN" }],    "skipped_orders": [{ "order_id": "uuid", "reason": "NOT_QUEUED" }]  },  "message": "Trips created and assigned"}

• status is DISPATCHED when auto_assign is true, otherwise PENDING_APPROVAL.

• sequence is the drop order inside the trip, starting at 0.

• track_url is the customer tracking link of that order. It is null while the batch is PENDING_APPROVAL.

• unassigned_orders are valid orders the optimiser could not place. They stay queued for the next call. reason is currently always UNKNOWN.

• skipped_orders are ids from order_ids that were not eligible. reason is NOT_FOUND (also used for another outlet’s order), NOT_OUTLET_MODE, NOT_QUEUED or CANCELLED.

Errors#

Approve a batch#

If you used auto_assign: false, approve the batch in the outlet portal (see Review, adjust and approve each rider’s route) or with the API:

curl -X POST "$BASE_URL/api/trips/batches/$BATCH_ID/approve" \  -H "Authorization: Bearer $ACCESS_TOKEN"

It approves a PENDING_APPROVAL batch of your outlet and returns the same data shape, with empty unassigned_orders and skipped_orders. 404 NOT_FOUND if the batch does not exist or was already processed.

Read trips#

• GET /api/trips/:tripId returns one trip of your outlet: trip_id, batch_id, status, distance_km, delivery_executive, orders (in drop order, with status and track_url), created_at, started_at, completed_at.

• GET /api/trips lists your trips, newest first. Query status: active (the default: PENDING_APPROVAL, CREATED, ASSIGNED, STARTED), completed or all. limit is 1 to 100 (default 50). cursor takes data.next_cursor from the previous page. The response has data.trips and data.next_cursor (null on the last page).