Async Order Acceptance & Rejection

Overview

By default, when Stream sends an order to the POS via a New Order Event, the POS is expected to immediately respond with either successful order acceptance or rejection with validation errors.

Some POS integrations require additional time to process orders before making an acceptance decision. The deferred confirmation pattern supports manual review or extended validation processes if your POS requires.

Default Order Flow

When orders originate from a DSP (Delivery Service Provider), the standard flow is:

1. Stream receives an order from the DSP
2. Stream runs internal validations (catalog existence, custom price rules, etc.)
3. Stream sends the order to the POS
4. The POS immediately responds with order acceptance or rejection with validation errors
5. Stream notifies the DSP whether the order was accepted or rejected

Deferred Order Confirmation Flow

1. Stream receives an order from the DSP
2. Stream runs internal validations (catalog existence, custom price rules, etc.)
3. Stream sends the order to the POS
4. The POS immediately responds with async_acceptance: true
   • The POS may queue the order for manual review
   • The POS may run additional internal validations
   • The order remains in a pending state
5. The POS sends a webhook event to Stream with order acceptance or rejection
6. Stream notifies the DSP whether the order was accepted or rejected

Timeout Behavior

If the POS does not send a confirmation webhook within 60 seconds of returning async_acceptance: true:

• Stream will automatically reject the order
• The rejection will include a confirmation_timeout error
• The DSP will be notified of the failure

Responding with Deferred Acceptance

When your POS needs additional time to process an order, respond to the New Order Event with:

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

Key Points:

• async_acceptance: true signals that a follow-up webhook will be sent
• The order will not automatically transition to accepted status
• You must send a status update webhook within 60 seconds

Sending Order Confirmation

After reviewing or validating the order, send a status update using the Handle Webhook Event endpoint.

Accepting the Order

To confirm the POS has accepted the order, use AsyncPOSOrderConfirmationEventObject:

Request Body:

{
  "type": "order.status.update",
  "object": {
    "provider_id": "pos-order-123",
    "location_id": "location-456",
    "status": "in_progress",
    "prep_time_minutes": 15
  }
}

Fields:

• provider_id (required): Your POS order ID
• location_id (required): Your POS location ID
• status (required): Must be "in_progress"
• prep_time_minutes (optional): Estimated preparation time

Rejecting the Order

To reject the order with validation details, use AsyncPOSOrderFailureEventObject:

Request Body:

{
  "type": "order.status.update",
  "object": {
    "provider_id": "pos-order-123",
    "location_id": "location-456",
    "status": "failed",
    "posValidation": {
      "orderValidation": [
        {
          "order_error": "store_unavailable",
          "order_error_reason": "Store is closed for maintenance"
        }
      ]
    }
  }
}

Validation Error Types

See the Order Rejection & Validation documentation for complete details on validation types and error codes.

Quick Reference

Stock Validation:

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

Order Totals Validation:

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

Order Validation:

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

Accepted Error Codes:

• invalid_cart - Cart is invalid or corrupted
• pos_offline - POS system is unreachable (transient error)
• store_unavailable - Store cannot accept orders
• other - Unspecified error (include details in order_error_reason)

Best Practices

• Respond quickly: Send status updates within 10-15 seconds when possible
• Always send a webhook: Every async_acceptance: true response must be followed by a status update
• Include detailed errors: Provide specific validation details to help troubleshoot rejections
• Monitor timeouts: Track how often orders timeout and optimize your review process