In-Store Orders

Overview

When a merchant creates an order directly in your POS system (such as call-in orders, walk-in orders, or other first-party orders), you can submit these orders to Stream for processing through the Handle Webhook Event (POS -> Stream) endpoint.

This allows Stream to handle dispatch, delivery coordination, and other fulfillment services for orders that originated in your POS system rather than from a DSP.

Special Considerations

• Call-in Orders: These are typically created manually in the POS and may require additional customer information collection
• Walk-in Orders: Orders placed in person that may need delivery coordination
• Future Orders: Orders scheduled for later pickup or delivery should include requested_for timestamp
• Payment Processing: In-store orders may have different payment processing requirements than third-party orders

Submitting In-Store Orders

To submit an in-store order to Stream, send a POST request to the webhook endpoint with the order.created event type:

Endpoint: POST /pos/{partner_slug}/webhook

Request Body:

{
  "type": "order.created",
  "object": {
    "idempotency_key": "pos_order_123_1699564800",
    "source_order_id": "pos_order_123",
    "source": "your_pos_name",
    "brand": "your_brand_name",
    "fulfillment_type": "delivery",
    "placed_at": 1699564800000,
    "is_future_order": false,
    "should_include_utensils": true,
    "customers": [
      {
        "id": "customer_1",
        "name": "John Doe",
        "phone": "+1234567890",
        "email": "john.doe@example.com"
      }
    ],
    "delivery_address": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "12345",
      "country": "US"
    },
    "line_items": [
      {
        "provider_id": "item_789",
        "name": "Cheeseburger",
        "quantity": 2,
        "price_amount": 1200,
        "price_currency": "usd",
        "customer_id": "customer_1",
        "modifiers": [
          {
            "provider_id": "modifier_101",
            "name": "Extra Cheese",
            "quantity": 1,
            "price_amount": 100,
            "price_currency": "usd",
            "modifiers": []
          }
        ]
      }
    ],
    "subtotal": 2600,
    "tax": 208,
    "tax_withheld_by_dsp": 0,
    "special_instructions": "Extra crispy fries please",
    "unpaid": false
  }
}

Order Processing Flow

Once an in-store order is successfully submitted to Stream:

1. Order Acceptance - Stream returns a 200 status code confirming order receipt
2. Dispatch Processing - For delivery orders, Stream coordinates with delivery partners
3. Status Tracking - Track order progress through Stream's order management system
4. Customer Communication - Stream handles customer notifications and updates throughout fulfillment

Updating Order Status

Send status updates for in-store orders using the same webhook endpoint.

Example:

{
  "type": "order.status.update",
  "object": {
    "provider_id": "pos_order_123",
    "location_id": "location_456",
    "status": "ready_for_pickup"
  }
}

Available Status Values:

Status	Description
ready_for_pickup	Order is prepared and ready for pickup by customer or driver
completed	Order has been completed (picked up or delivered)
merchant_canceled	Order has been canceled from the POS

Canceling In-Store Orders

To cancel an in-store order that has been submitted to Stream, send a cancelation status update:

{
  "type": "order.status.update",
  "object": {
    "provider_id": "pos_order_123",
    "location_id": "location_456",
    "status": "merchant_canceled"
  }
}

Cancelation Best Practices

• Act quickly: Cancel orders as soon as you know they cannot be fulfilled
• Provide reasons: Include clear cancelation reasons when possible
• Update inventory: Adjust inventory levels after cancelations
• Notify staff: Ensure kitchen staff are aware of canceled orders