Stream Order Status Updates

Overview

Stream sends order status updates to your POS system throughout the lifecycle of an order. These updates inform your POS of changes to the order state, delivery progress, and driver information as the order moves through fulfillment. Not all DSPs provide full status updates, so the availability of certain statuses may vary by order source.

Receiving Status Updates

When an order is updated within Stream or by the DSP, you will receive an order.updated event to the Handle Order (Stream -> POS) endpoint.

Event Structure:

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "out_for_delivery",
    "delivery_status": "enroute_to_dropoff",
    "driver_details": {
      "source": "doordash",
      "name": "John Driver",
      "phone": {
        "number": "+15555551234",
        "code": "123"
      },
      "vehicle_info": {
        "make": "Toyota",
        "model": "Camry",
        "color": "Silver",
        "license_plate": "ABC1234"
      }
    }
  }
}

Order Status Values

The status field indicates the overall state of the order:

Status	Description
in_progress	Order is being prepared
ready_for_pickup	Order is prepared and ready for driver/customer pickup
out_for_delivery	Order has been picked up and is being delivered
completed	Order has been delivered or picked up - fulfillment complete
failed	Order could not be fulfilled
merchant_canceled	Order was canceled by the merchant
dsp_canceled	Order was canceled by the DSP or customer

Delivery Status Values

For delivery orders, the delivery_status field provides detailed tracking of the delivery progression:

Pre-Pickup Statuses

Status	Description
pending	Delivery is in quoted state, not yet confirmed
pending_driver_confirmation	Waiting for a driver to be assigned to the order
enroute_to_pickup	Driver is on the way to the restaurant to pick up the order
arrived_at_pickup	Driver has arrived at the restaurant

Post-Pickup Statuses

Status	Description
enroute_to_dropoff	Driver has picked up the order and is heading to customer
arrived_at_dropoff	Driver has arrived at the customer's location
completed	Order has been successfully delivered

Failure Statuses

Status	Description
failed_to_assign_driver	No driver could be assigned to the order
failed_to_pickup	Driver was unable to pick up from restaurant
failed_to_deliver	Driver was unable to deliver to customer
failed	General delivery failure
merchant_canceled	Merchant canceled the order during delivery

Return Statuses

Status	Description
enroute_to_return	Driver is returning the order to the restaurant
arrived_at_return	Driver has arrived back at the restaurant
returned	Order has been returned to the restaurant

Driver Details

When a driver is assigned to an order, the driver_details object provides information about the driver and their vehicle:

{
  "driver_details": {
    "source": "doordash",
    "name": "John Driver",
    "phone": {
      "number": "+15555551234",
      "code": "123"
    },
    "picture_url": "https://example.com/driver.jpg",
    "vehicle_info": {
      "make": "Toyota",
      "model": "Camry",
      "color": "Silver",
      "license_plate": "ABC1234",
      "is_autonomous": false
    },
    "handoff_instructions": "Meet driver at front entrance",
    "passcode": "1234"
  }
}

Field Descriptions:

• source : The delivery platform providing the driver
• name : Driver's name
• phone : Driver's contact number with optional masking code
• picture_url : URL to driver's profile picture
• vehicle_info : Details about the delivery vehicle
  • make: Vehicle manufacturer
  • model: Vehicle model
  • color : Vehicle color
  • license_plate : License plate number
  • is_autonomous: true if the delivery is by robot/autonomous vehicle
• handoff_instructions : Instructions for handing off the order
• passcode : Passcode to verify the driver's identity

Example Status Updates

Driver Assigned and En Route

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "out_for_delivery",
    "delivery_status": "enroute_to_pickup",
    "driver_details": {
      "source": "uber",
      "name": "Jane Driver",
      "phone": {
        "number": "+15555555678"
      },
      "vehicle_info": {
        "make": "Honda",
        "model": "Civic",
        "color": "Blue"
      }
    }
  }
}

Driver Arrived at Restaurant

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "ready_for_pickup",
    "delivery_status": "arrived_at_pickup",
    "driver_details": {
      "source": "uber",
      "name": "Jane Driver",
      "passcode": "5678"
    }
  }
}

Order Out for Delivery

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "out_for_delivery",
    "delivery_status": "enroute_to_dropoff"
  }
}

Order Completed

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "completed",
    "delivery_status": "completed"
  }
}

Autonomous Delivery (Robot)

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "out_for_delivery",
    "delivery_status": "enroute_to_pickup",
    "driver_details": {
      "source": "kiwibot",
      "name": "Kiwi Robot #42",
      "vehicle_info": {
        "make": "Kiwibot",
        "model": "K3",
        "color": "Green",
        "is_autonomous": true
      },
      "handoff_instructions": "Place order in robot's compartment",
      "passcode": "9876"
    }
  }
}

Delivery Failed

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "failed",
    "delivery_status": "failed_to_deliver"
  }
}

Order Canceled by DSP

{
  "type": "order.updated",
  "object": {
    "location_id": "pos_location_456",
    "order_id": "pos_order_123",
    "status": "dsp_canceled"
  }
}