Order Management

Order Ingestion

After a merchant connects one of your locations to Stream, you will be able to send orders to us to forward to their POS system.

To send orders to Stream to forward to their POS system via the New Webhook Event (DSP -> Stream) endpoint.

Order Identifiers

To ensure successful ingestion of the order, ensure the line item identifiers align with the following.

Order Field	Menu Field	Menu V2 Field
Order.items[x].id	Menu[x].categories[x].items[x].variations[x].stream_id	MenuV2[x].categories[x].item_families[x].items[x].stream_id
Order.items[x].item_id	Menu[x].categories[x].items[x].stream_id	MenuV2[x].categories[x].item_families[x].stream_id
Order.items[x].modifiers[x].id	Menu[x].categories[x].items[x].modifier_groups[x].modifiers[x].stream_id	MenuV2[x].categories[x].item_families[x].modifier_groups[x].modifiers[x].stream_id
Order.items[x].modifiers[x].modifier_group_id	Menu[x].categories[x].items[x].modifier_groups[x].stream_id	MenuV2[x].categories[x].item_families[x].modifier_groups[x].stream_id

After we process an order, there are multiple actions that may take place before the final fulfillment of the order. These actions include:

Accepting Orders

When an order is successfully injected into the merchant's POS system, we will notify you via the New Webhook Event (Stream -> DSP) endpoint with an event type of location.order.accept.

Failing Orders

When we are unable to inject an order into the merchant's POS system, we will notify you via the New Webhook Event (Stream -> DSP) endpoint with an event type of location.order.fail.

The fail event payload includes a failure_reason indicating why the order could not be processed, along with optional failure_details providing additional context.

Failure Reasons:

Reason	Description
restaurant_not_accepting_orders	The restaurant is not currently accepting new orders (e.g. the store is paused or offline in POS).
location_not_found	The location could not be found in Stream.
pos_missing_items	One or more items in the order do not exist in the POS menu.
items_unavailable	One or more items in the order are currently marked as unavailable (86'd).
order_validation_error	The order failed validation (e.g. missing required fields or invalid modifiers).
unknown	The failure reason could not be determined. See below.

When does unknown occur?

An unknown failure reason is returned when Stream cannot map the failure to a specific cause. This typically happens when:

• Order information issues — The order payload contains data that the POS cannot process, but the POS does not return a specific error code that Stream can categorize.
• Retry exhaustion — Stream was unable to successfully inject the order after multiple retry attempts (e.g. due to transient POS connectivity issues or timeouts), and the order ultimately failed without a classifiable error.

If you are seeing a high volume of unknown failures, reach out to the Stream team for assistance in diagnosing the root cause.

Failure Details:

The failure_details object may include:

• invalid_item_ids — An array of item IDs that contributed to the failure (e.g. for pos_missing_items or items_unavailable).
• error_message — A human-readable message describing the error that occurred.

See full fail event payload.

Notifying Order Status Change

When the status of an order changes in a way that affects the customer (e.g. Ready to pickup, Out for delivery), we will notify you via the New Webhook Event (Stream -> DSP) endpoint with an event type of location.order.notify_status_change.

The completed status is only sent if the merchant performs the completion of the order in POS or Stream. If the order status changes to completed from an automated expiration, you will not recieve this event.

Order Discounts

On your order submission, you can include a discount to be applied to the order. This discount will be applied to the order subtotal when inserting into the merchant's POS system.

{
  "order": {
    "id": "1234567890",
    "discounts": [
      {
        "amount": 1000,
        "id": "MERCHANT_DISCOUNT_ID",
        "item_id": "OPTIONAL_ITEM_ID"
      }
    ]
  }
}

Canceling Orders

Although we do our best to make sure that orders that can not be fulfilled do not get accepted. Sometimes orders are accepted and then canceled by the merchant. When this happens, we will notify you via the New Webhook Event (Stream -> DSP) endpoint with an event type of location.order.cancel.

The cancel order event payload may include:

• cancel_source (optional): Who initiated the cancelation. Accepted values: customer, restaurant, driver, dsp.
• cancel_reason (optional): The reason for the cancelation. Can be one of the normalized values (e.g. customer_requested, item_out_of_stock, store_closed, driver_unavailable, payment_failed, other) for cross-DSP reporting.

See full cancel order payload.

If a customer decides to cancel an order from your platform, you can notify us via the New Webhook Event (DSP -> Stream) endpoint.