Orders
The Order entity represents the core component of the Ordering API, containing all relevant information about an order placed by customers at a given location. An order can consist of multiple items, each with details like status, quantity, price, and applied modifiers. Dojo products create, modify and retrieve orders on the POS via the EPOS Data component of the Dojo API, these capabilities are documented below.
Status
The Order Status represents the various stages in an order’s lifecycle. As an order progresses from creation to fulfilment, its status will update to reflect its current state.
| Status | Description |
|---|---|
New | The order has been created but has not yet been processed. |
Submitted | The order has been submitted to the EPOS and is awaiting confirmation. |
Confirmed | The order has been confirmed by the EPOS and is awaiting kitchen or staff to accept. |
Accepted | The order has been accepted by the kitchen or staff for preparation. |
Preparing | The items in the order are currently being prepared. |
Prepared | The items have been fully prepared and are ready for service or collection. |
Ready | The order is ready for delivery or collection by the customer. |
Finalized | The order has been completed and paid for, and no further changes can be made. |
Canceled | The order has been canceled and is no longer active. |
Failed | The order has encountered an error and failed to process. This may require further investigation. |
These statuses help track the state of each order and ensure that any integrated systems can react to updates in a consistent manner.
Capabilities
In the Dojo EPOS Data API, capabilities represent specific actions that the POS system can perform. These capabilities are linked to corresponding API endpoints in the POS system. By defining these capabilities, the POS system communicates to Dojo which features are supported and accessible.
CreateOrder
POST REST /v1/orders
This capability allows the creation of new orders within the POS system. It is essential for handling customer orders and storing relevant order details.
GetOrderById
This capability enables the POS system to retrieve detailed information about a specific order using its unique order ID. This is crucial for order tracking and status updates.
CancelOrderById
DELETE REST /v1/orders/{orderId}
This capability provides the ability to cancel an order within the POS system, preventing further modifications or processing. Cancellations are performed using the order’s unique ID. The POS system can reject a CancelOrder reqeuest if the order is not in a state where it can be cancelled.
SearchOrders
POST REST /v1/orders
This capability enables searching for orders based on various criteria. It supports filtering and pagination to help Dojo products efficiently find orders within the POS system. Each Dojo product has different requirements on what filters must be implemented which can be found on the product documentation page(s).
CreateOrderLock
POST REST /v1/orders/{orderId}/lock
This capability allows Dojo to acquire a lock on orders before making modifications to it like recording payments or adding items. These locks allow the EPOS to know when an Order being modified and give Dojo the guarantee that the Order will not be modified externally while these operations are taking place. Dojo will only try to acquire when making modifications, for other purposes fetching an eventually consistent snapshot of an Order from the EPOS through GetOrder should always be possible.
| Registered capabilities | Behaviour |
|---|---|
| RecordOrderPayment | Dojo will send the RecordOrderPayment request, if a Conflict error is returned Dojo will attempt to reverse the payment |
| RecordOrderPayment, CreateOrderLock, DeleteOrderLock | Dojo will first try to create the order lock with a long expiry. If successful it will try to record one or multiple payments then delete the lock. |
| RecordOrderPayment, CreateOrderLock, DeleteOrderLock, ExtendOrderLock | Dojo will first try to create the order lock with a short expiry. If successful it will try to record one or multiple payments. If the payment session takes longer, it will extend the lock. After the payment session has finished we will delete the lock. |
DeleteOrderLock
DELETE REST /v1/orders/{orderId}/locks/{lockId}
This capability allows Dojo to release a lock on orders. If both this and CreateOrderLockRequest are registered then Dojo will only attempt to RecordOrderPayment against an order after having successfully acquired a lock and will release the lock once the payment is recorded.
ExtendOrderLock
PUT REST /v1/orders/{orderId}/locks/{lockId}
This capability allows Dojo to extend an existing lock. It is not required for the locking flow to function, registering this will allow Dojo to create locks with a shorter initial expiry and extend as needed.
RecordOrderPayment
POST REST /v1/orders/{orderId}/record-payment
This capability allows Dojo to record a payment against an order. All payments recorded this way will be sent with their Payment Intent ID which is unique and can be used for both deduplication and to control the lifecycle of the payment with operations like Get and Reversal.