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
| Type | Example |
|---|---|
| Stock Validation | Item/Modifier Inventory Checks |
| Order Totals Validation | Order SubTotal Greater Than Or Equal POS Check |
| Order Validation | Other 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 IDquantity(required): The remaining available quantitytype(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 Retriesstore_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 inorder_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.
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.
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.
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.