Skip to main content

Order Acceptance

Overview​

When Stream sends an order via the Handle Order (Stream -> POS) endpoint, your POS must respond to indicate whether the order can be fulfilled.

Standard Order Acceptance​

Upon a successful 200 response with order.created event type, Stream considers the order accepted and inserted into the POS successfully. At this point, the DSP is notified that the order is accepted.

Required Response Fields​

The only required field in a successful 2xx response is:

  • order.provider_id - Your POS order ID, used for all future communication about this order

Response Example​

{
"order": {
"provider_id": "pos-order-12345",
"prep_time_minutes": 15
}
}

Timeouts and Retries​

Response timeout​

Stream waits up to 60 seconds by default for your response to Handle Order (Stream -> POS). Stream can set a different timeout for your integration on request. If no response arrives in time, the attempt counts as failed and is retried.

If your POS needs longer than that to decide, respond straight away with async_acceptance: true and confirm by webhook instead. See Async Order Acceptance.

Which responses Stream retries​

Your responseWhat Stream does
2xx with order.provider_idOrder accepted (or pending, with async_acceptance: true). No retry.
400 or 500 with orderValidation order_error: pos_offlineTreated as temporary. Retried. If the attempts run out, the order fails as POS offline.
400 or 500 with stockValidationOrder rejected as out of stock. No retry. On some delivery platforms Stream may instead remove or reduce the unavailable items and send you the adjusted order (see below).
400 or 500 with orderTotalsValidation, or orderValidation with any other order_errorOrder rejected with that reason. No retry. See Order Rejection & Validation.
400 or 500 with an empty posValidation objectTreated as temporary. Retried.
Any other non-2xx (for example 500, 502, 503), a 2xx without order.provider_id, or no response within the timeoutTreated as temporary. Retried.

Stream reads stockValidation first, then orderTotalsValidation, then orderValidation, and uses the first one that has entries. Only the first orderValidation entry is read.

Retry schedule​

Retries back off exponentially from 10 seconds: 10 s, 20 s, 40 s, 80 s, then 160 s. That is up to 6 attempts, with the last one starting about 5 minutes after the first (plus the time each attempt takes). Some delivery platforms give Stream less time to confirm an order. For those, Stream makes fewer attempts, for example 5, with the last one about 2.5 minutes after the first.

When the attempts run out, the order fails and the delivery platform is told it was not accepted.

caution

A request that timed out may already have created the order in your POS. Every retry sends the same idempotency_key. If you have already created an order for that key, return its order.provider_id again rather than creating a second order.

After a stockValidation rejection, the adjusted order arrives as a new order.created with the same idempotency_key and the reduced line_items. Because you rejected the earlier request, no order exists for that key yet, so create it as normal.

Once you have accepted asynchronously, there are no further retries. The 60-second confirmation window described in Async Order Acceptance applies.

Dynamic Prep Time​

Stream manages preparation time at two levels. Understanding both is important for providing accurate timing to customers at each stage of the order flow.

Location-level prep time (location.prep_time_minutes)​

Set on your Get Locations response, this is the default prep time for the location. DSPs use this value to display estimated wait times to customers before they place an order — for example, on a storefront listing. It is a static value that represents your typical preparation time under normal conditions.

{
"provider_id": "location_123",
"name": "Downtown Branch",
"prep_time_minutes": 20
}

To update this value, you would need to trigger a location resync.

Order-level prep time (order.prep_time_minutes)​

Returned in your order acceptance response, this is an optional per-order override of the location-level prep time. DSPs use this value to display a confirmed preparation time to the customer after their order is placed and accepted.

If order.prep_time_minutes is not included in your acceptance response, Stream will fall back to the location's prep_time_minutes automatically — no resync required.

{
"order": {
"provider_id": "pos-order-12345",
"prep_time_minutes": 12
}
}

Use this field to dynamically adjust prep time per order based on real-time factors such as:

  • Current kitchen load
  • Order complexity
  • Time of day
  • Staff availability

Future Orders​

Some DSP platforms support scheduling orders in advance. When this occurs:

  • is_future_order will be set to true
  • requested_for will contain the estimated fulfillment time

Other DSP platforms, for example, Uber & DoorDash, hold the order on their end and notify Stream closer to the fulfillment time. You will not receive advance indication that it was a future order.

Async Order Acceptance​

If your POS integration needs additional time to validate or manually review orders before acceptance, see Async Order Acceptance for the deferred acceptance workflow.

When to Use Async Acceptance​

Use async acceptance when your POS needs to:

  • Queue orders for manual review by staff
  • Run extended validation processes
  • Check external systems before confirming

Quick Example​

Respond with async_acceptance: true to defer the decision:

{
"order": {
"provider_id": "pos-order-123",
"prep_time_minutes": 15,
"async_acceptance": true
}
}

Then send a webhook event within 60 seconds to confirm or reject.

See the full async order acceptance documentation for complete details.

Order Rejection​

If your POS cannot fulfill the order, return a 400 status code with validation details. See Order Rejection & Validation for details on validation types and error formats.