Online Ordering Subscriptions

Authorization (HMAC)

To verify that the payloads your webhooks receive actually come from us, we require that you implement HMAC authentication schema.

HMAC constructs an information-rich header that contains information about the sender, while providing security to ensure that the request has not been forged or tampered with in transit.

For more information read here

Available Subscriptions

Request to Change Order Status created
Request to Confirm Order created
Request to Reject Order created
Request to Void Order created
Request to Fulfill Order created
Request to Refund Order created
Request to make an Order Ready For Pickup created
Request to make an Order Out For Delivery created
Request to Update Menu Item Stock Status

Request to Change Order Status created

This event is triggered when a merchant submits a request to change the status of the order on the POS side. After this action, Order is locked (action is pending) in the POS, until an Order with the changed status is pushed back to it. Since this event accommodates all of the possible status updates, if the app is subscribed to any of the more granular events, only the latter will be sent out in any relevant situation.

Payload:

Name	Type	Description
status*	string	New status which is requesting to change by POS.
locationId*	integer	The Lighthouse location ID.
orderId*	string	The order identifier which was generated during Order creation.
waitTimeInMinutes	integer	Required only if status `CONFIRMED`. This represents the remaining wait time in minutes. If this is a delivery order, it is the estimated number of minutes until delivery to the diner.
reasons	array	Required only if status `REJECTED`. Array of rejection reasons for rejecting the order. At least one reason is provided. Example: { ...., "reasons": [ { "code": "ITEMS_OUT_OF_STOCK", "explanation": "Item is out of stock", "refs": [ "b4b6a5d6-426a-4d02-b7c7-705981b5c9cd", "ef52c3c1-17d6-4759-9dc6-58301a5d8894" ] } } }

Response:

Successful response 2xx is expected.

In case of a conflicting status, response 409 is expected with a conflict reason:

{
  "message": null, // optional error message
  "status": "REJECTED", // current status of the order, required
  "reason": {
    "code": "ORDER_CONFIRMATION_WINDOW_EXPIRED",
    "explanation": "The Confirmation Window has been expired"
  }
}

Request to Confirm Order

This event is triggered when a merchant submitted an confirmation action in POS side.

Event Example:

{
  "event": {
    "name": "online-ordering.OrderStatusChangeRequest.created",
    "component": "online-ordering",
    "resource": "OrderStatusChangeRequest",
    "action": "created",
    "version": "v3",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "status": "CONFIRMED",
    "locationId" : "{{locationId}}",
    "orderId": "{{orderId}}",
    "waitTimeInMinutes": 100
  }
}

3rd-party is responsible to process a confirmation on their side by changing and pushing back an updated Order.

In general confirmation the process is affecting those Order attributes:

Name	Type	Description
status*	string	Change status to: `CONFIRMED`
statusHistory*	integer	Add an order confirmation status at `statusHistory`. The status source should be `APP`.
estimatedAt	string	Re-calculate an order estimation depending on `waitTimeInMinutes` when the food will be ready for pickup or delivered to the diner.

Request to Reject Order

This event is triggered when a merchant submits a rejection action on the POS side.

Event Example:

{
  "event": {
    "name": "online-ordering.OrderStatusChangeRequest.created",
    "component": "online-ordering",
    "resource": "OrderStatusChangeRequest",
    "action": "created",
    "version": "v3",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "status": "REJECTED",
    "locationId" : "{{locationId}}",
    "orderId": "{{orderId}}",
    "reasons": [
      {
        "code": "STORE_CLOSED",
        "explanation": "Restaurant is offline"
      }
    ]
  }
}

In general, the process of rejection is affecting the following attributes of an Order:

Name	Type	Description
status*	string	Change status to: `REJECTED`
statusHistory*	integer	Add an order confirmation status at `statusHistory`. The status source should be `APP`.

Rejection reason

Name	Type	Description
code*	string	Rejection reason code. Supported rejection reason codes
explanation*	string	Rejection reason explanation
refs	array	Required only for "resource" specific reason codes, etc, "MISSING_ITEMS"

Supported rejection reason codes

Code	Examples
POS_NOT_SETUP	POS/AGENT configuration issue
POS_NOT_READY	Sale ring up in progress Drawer/Till open End of Day batchout in progress
POS_OFFLINE	POS Offline Internet Outage Technical issue in-store
STORE_CLOSED	Store closed Orders submitted outside of operational hours Holiday Hours not honored
STORE_CAPACITY	No open capacity slots Invalid pickup times Rejected due to busy store
ORDER_INFO_MISSING	Missing required Order detail
ORDER_ADDRESS_INVALID	Missing required address Invalid geo-coordinates and/or textual identifier
ORDER_SPECIAL_INSTRUCTIONS	Allergen info provided on order Utensil opt-in / opt-out instruction
ORDER_TOTALS_MISMATCH	Mismatch in expected subtotal Incorrect Tender format
ITEMS_OUT_OF_STOCK	Order contains out of stock items Invalid items references expected
ITEMS_NOT_AVAILABLE	Item not available during service hours (Breakfast, Lunch, Late Night, etc.)
ITEMS_INFO_MISSING	Item is missing a required choice selection Invalid quantity rules set in the menu on parent modifier group
ITEMS_PRICING_MISMATCH	Mismatch in item pricing
ITEMS_SPECIAL_INSTRUCTIONS	Item level instructions on order
MODIFIERS_OUT_OF_STOCK	Order contains out of stock items
MODIFIERS_NOT_AVAILABLE	Item not available during service hours (Breakfast, Lunch, Late Night, etc.)
MODIFIERS_PRICING_MISMATCH	Mismatch in item pricing
ORDER_CONFIRMATION_WINDOW_EXPIRED	The POS requested to confirm the order after its confirmation window has been expired on the 3rd-party side
OTHER	Generic Error Response Blank/Null Response

Request to Change Status

This event is triggered when a merchant performs any other status-changing action (READY_FOR_PICKUP, OUT_FOR_DELIVERY, FULFILLED and etc.) on the POS side.

Event Example:

{
  "event": {
    "name": "online-ordering.OrderStatusChangeRequest.created",
    "component": "online-ordering",
    "resource": "OrderStatusChangeRequest",
    "action": "created",
    "version": "v3",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "status": "READY_FOR_PICKUP",
    "locationId" : "{{locationId}}",
    "orderId": "{{orderId}}"
  }
}

In general, the process of rejection is affecting the following attributes of an Order:

Name	Type	Description
status*	string	Change status to a requested one (`READY_FOR_PICKUP`, `OUT_FOR_DELIVERY`, `FULFILLED` and etc.)
statusHistory*	integer	Add an order confirmation status at `statusHistory`. The status source should be `APP`.

Request to Confirm Order created

This event is triggered when a merchant confirms the order on the POS.

{
  "event": {
    "name": "online-ordering.OrderConfirmRequest.created",
    "component": "online-ordering",
    "resource": "OrderConfirmRequest",
    "action": "created",
    "version": "v3",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": <OrderStatusChangeRequestPayload>
}

3rd-party is responsible to process a confirmation on their side by changing and pushing back an updated Order.

In general confirmation the process is affecting those Order attributes:

Name	Type	Description
status*	string	Change status to: `CONFIRMED`
statusHistory*	integer	Add an order confirmation status at `statusHistory`. The status source should be `APP`.
estimatedAt	string	Re-calculate an order estimation depending on `waitTimeInMinutes` when the food will be ready for pickup or delivered to the diner.