Skip to main content

Order Rejection & Validation

Overview​

When an order insertion is attempted into the POS, you should perform validations to ensure the order criteria can be met.

Validation Types​

TypeExample
Stock ValidationItem/Modifier Inventory Checks
Order Totals ValidationOrder SubTotal Greater Than Or Equal POS Check
Order ValidationOther Errors That Do Not Require Structured Info

Rejecting Orders with Validation Errors​

To reject an order during initial acceptance, return a 400 status code to the Handle Order (Stream -> POS) endpoint with validation details:

{
"posValidation": {
"stockValidation": [
{
"type": "item",
"provider_id": "string",
"quantity": 0
}
],
"orderTotalsValidation": [
{
"posTotal": 0,
"streamTotal": 0
}
],
"orderValidation": [
{
"order_error": "string",
"order_error_reason": "string"
}
]
}
}

Stock Validation​

Use when items or modifiers are out of stock or have insufficient quantity:

{
"stockValidation": [
{
"provider_id": "item-789",
"quantity": 3,
"type": "item"
}
]
}

Fields:

  • provider_id (required): The item or modifier's provider ID
  • quantity (required): The remaining available quantity
  • type (required): Either "item" or "modifier"

Order Totals Validation​

Use when there's a price mismatch between Stream and your POS:

{
"orderTotalsValidation": [
{
"posTotal": 2550,
"streamTotal": 2500
}
]
}

Fields:

  • posTotal (required): Total calculated by your POS (in cents)
  • streamTotal (required): Total sent by Stream (in cents)

Order Validation​

Use for general order-level errors:

{
"orderValidation": [
{
"order_error": "store_unavailable",
"order_error_reason": "Store is closed until 5pm"
}
]
}

Accepted Error Codes​

  • invalid_cart - The submitted cart is invalid (empty cart, items no longer available, mismatched pricing/discounts, or corrupted cart session)
  • pos_offline - The POS system is unreachable or offline due to network issues, maintenance, or service outage. Stream retries the order before failing it; see Timeouts and Retries
  • store_unavailable - The store cannot accept orders (temporarily closed, not fulfilling orders, or constrained by inventory/fulfillment rules)
  • other - An unspecified or unknown validation error occurred. Include detailed diagnostic information in order_error_reason

Rejections vs. Retries​

Stream only treats a response as a rejection when it can read a posValidation body. Anything else is treated as temporary and retried for several minutes. See Timeouts and Retries for the full list of retried responses, the backoff schedule, and how to use idempotency_key to avoid duplicate orders.

caution

A 500 with a posValidation body is a rejection, not a retry. Stream reads the validation body on a 500 just as on a 400, so the order fails at once (unless the order_error is pos_offline). To ask Stream to try again, return a 5xx with no posValidation, or use pos_offline.

caution

Rejecting with a bare 400 (no posValidation) delays the failure by minutes. Stream cannot tell it apart from a temporary error, so it retries until the attempts run out and then fails the order with a generic reason. Always include posValidation when you reject an order.

caution

posValidation on any status other than 400 or 500 is ignored. A 422 or 409 with a validation body is retried like any other error. Use 400 for rejections.

Validation in Async Orders​

For orders using async order acceptance, validation errors should be sent via webhook instead of in the initial HTTP response. See the async order acceptance documentation for details.