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 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
• 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

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.