Update Fulfillment Status

POST {{BASE_HABITAT_URL}}/api/v3/orders/{{ORDER_ID}}/status

Required scope: orders:write

If you operate your own fleet, and runners are not using the First Runner app, you can remotely update the status of an order, and send runner location updates, via this endpoint.

Status updates can be one of those available in the Status section. To send just a runner location update, pass null as the value for status.

Attempting to update the status of an order being fulfilled by a fleet in our DSP network will return a 400 error.

Request body

{
   "status": "{{ORDER_STATUS}}",
   "payload": {
       "runner_id": "{{RUNNER_ID}}",
        "location":  {
             "latitude": 90,
             "longitude": 84
           }
   }
}

Examples

cURL

curl --request POST '${BASE_HABITAT_URL}/api/v3/orders/${ORDER_ID}/status' \
  --data '{
   "status": "{{ORDER_STATUS}}",
   "payload": {
       "runner_id": "{{RUNNER_ID}}",
        "location":  {
             "latitude": 90,
             "longitude": 84
           }
   }
}'

Node.js

const response = await fetch("${BASE_HABITAT_URL}/api/v3/orders/${ORDER_ID}/status", {
  "method": "POST",
  "headers": {},
  "body": "{\n   \"status\": \"{{ORDER_STATUS}}\",\n   \"payload\": {\n       \"runner_id\": \"{{RUNNER_ID}}\",\n        \"location\":  {\n             \"latitude\": 90,\n             \"longitude\": 84\n           }\n   }\n}"
})
const data = await response.json()

Python

import requests

response = requests.request(
    "POST",
    "${BASE_HABITAT_URL}/api/v3/orders/${ORDER_ID}/status",
    headers={},
    data="{\n   \"status\": \"{{ORDER_STATUS}}\",\n   \"payload\": {\n       \"runner_id\": \"{{RUNNER_ID}}\",\n        \"location\":  {\n             \"latitude\": 90,\n             \"longitude\": 84\n           }\n   }\n}",
)
response.raise_for_status()

Saved responses

200 Update Status

{
    "type": "success",
    "data": {
        "id": "0ffeaeb0-c2bd-11ed-938e-6b0e25251d1d",
        "quote_id": "0fef6c70-c2bd-11ed-938e-6b0e25251d1d",
        "external_order_id": "12345",
        "external_order_reference": "1234",
        "dsps_delivery_id": null,
        "_request_id": "243e6565-2ed4-4869-9576-ea8ef6ffa759",
        "dsps_name": null,
        "created_at": "2023-03-14T23:07:59.149Z",
        "status": "pending_dispatch",
        "method": "Delivery",
        "timezone": "America/New_York",
        "pickup_name": "mikes test",
        "pickup_address": "2211 E Hagert St, Philadelphia, PA 19125, USA",
        "pickup_phone": "2333322311",
        "pickup_instructions": null,
        "pickup_lat": 39.98,
        "pickup_lng": -75.13,
        "dropoff_lat": 39.98,
        "dropoff_lng": -75.13,
        "route_distance_miles": 0.67,
        "dropoff_address": "2166 E Norris St., Philadelphia PA, 19125",
        "dropoff_suite": null,
        "dropoff_instructions": null,
        "customer_name": "Steve",
        "customer_phone": "2333344999",
        "payment_type": "credit_card",
        "pickup_estimate": "2023-03-14T23:27:58.553Z",
        "dropoff_estimate": "2023-03-14T23:32:58.553Z",
        "runner_assigned_at": null,
        "runner_accepted_at": null,
        "runner_arrived_origin": null,
        "runner_picked_up": null,
        "runner_arrived_dropoff": null,
        "runner_dropped_off": null,
        "cancelled_at": null,
        "contents": [
            {
                "itemName": "Cheeszteak"
            }
        ],
        "tip": 2,
        "order_total": 9,
        "runner": null,
        "merchant_id": "c9c8be91-c2bc-11ed-938e-6b0e25251d1d",
        "runner_id": null
    }
}