This page contains all the API actions for the checkout process.
API Actions
Make sure all this actions are performant and responses are provided in less than 3 seconds for p99. Long response times will translate into long loading times for guests.
Once guests have added items to cart, they will go to the cart page to understand total price and proceed with the order.
Price webhook and endpoint
When a guest goes to the cart page, the contents of their cart are priced against the POS and the final price is displayed to the customer.
To do that, we trigger the Price Order webhook, which signals that an order needs to be priced by the POS. The payload of the webhook includes the order contents for the selected store id and service mode.
The POS must return the price and availability for each item in the order, the total price and any errors using the Price Webhook Callback endpoint.
If there’s any errors that prevented a successful pricing, they should be reported using the partnerErrors field. Errors that prevent successful pricing can be related to menu items availability, store availability, POS technical issue, etc.
These pricing actions will trigger every time guests access the cart page.
Once guests are happy with their order, they will click on Continue and proceed to the payment page, where they will select their preferred payment method and proceed. The RBI platform takes care of the payment step.
Our API offers some control over payments, but these actions are typically not needed. You can learn more about payments here: Orders API - Payments .
Commit webhook and endpoint
Once guests have inputted their payment information and click on Place Secure Order, we consider the order placed.
When an order is placed, it needs to be acknowledge by and registered in the POS. Every time an order is placed we trigger the Commit Order webhook. The payload of the webhook includes payment details, the final total order price, customer details and “firing instructions".
Note that the Commit Order webhook payload does not include all order details because the POS has received all relevant information about the order previously via the pricing webhook (service mode, order number, etc.). You can also fetch all order information from the GET Order endpoint, at any time.
The POS must respond to the webhook request by using the Commit Webhook callback endpoint. In this callback, the POS should use the status COMMITTED .
If there’s any errors that prevented a successful commit, they should be reported using the partnerErrors field, and you should use the status ERROR instead. Errors that prevent a successful commit can be related to menu items availability, store availability, POS technical issue, etc.
Committing and order does not mean that the order should be prepared immediately. In the Commit Order webhook payload we include the fireOrderInSeconds field which indicates when order should be sent (or 'fired') to the kitchen for preparation.
The fireOrderInSeconds mechanism allows for guests to order for a future time and ensure that orders are only prepared at the right time.
For example,
| POS action |
|---|---|
60 | The order should be sent to the kitchen for preparation 60 seconds after the commit webhook. |
0 | The order should be sent to the kichen for preparation immediately. |
| The order should be held in the POS until a fire webhook is triggered. You can learn more about the fire mechanism below. |
Fire webhook & endpoint
As explained above, there’s a difference between committing an order and sending it for preparation. By ‘firing’ an order we refer to sending the order to the kitchen for preparation.
Only committed orders can be fired.
In the commit webhook payload, the fireOrderInSeconds indicates when the order should be sent to the kitchen.
The fire webhook can be triggered for any order that hasn’t been fired yet, regardless of the value of fireOrderInSeconds in the commit webhook payload. This means that the fire webhook can be triggered both when fireOrderInSeconds is null or higher than 0.
The fire request takes precedence over the fireOrderInSeconds value. This means that if a fire webhook is triggered for an order that has not reached the fireOrderInSeconds time, it should be sent to kitchen for preparation.
The POS must respond to the webhook by using the the Fire Webhook Callback endpoint. In this callback, the POS should use the status PREPARING.
If there’s any errors that prevent a successful firing, the status should instead be ERROR and the errors must be included in the errors field.
Order event webhook and endpoint
All order events are broadcasted through our order event webhook.
Order statuses must move forward in the lifecycle shown on the diagram below. Status updates that do not move the order status forward will be disregarded.
These are the order lifecycle statuses:
Status | Description | When does it trigger? |
|---|---|---|
CREATED | Order has been created. | When guests access the cart page. |
PRICED | Order has been priced. The POS has provided price information for the order. | When the POS returns price info via the Price Webhook Callback endpoint. |
COMMITTED | Order has been committed. The POS has accepted the order. | When the POS confirms the commit via the Commit Webhook callback endpoint. |
PREPARING | Order is being prepared in the restaurant | When the POS responds to the Fire Webhook Callback endpoint, or the |
PREPARED | Order has been prepared and is ready for pickup or delivery. | When the POS informs that the order is ready via the Order Event endpoint. |
DONE | Order is done. This is the final state for a successful order. | [ ] |
CANCELED | Order has been cancelled. | Canceled status can trigger in 3 different cases:
|
ERROR | Error with the order. Customer will be notified and refunded when applicable. | When the POS notifies us there’s been an error in the Price Webhook Callback endpoint or the Commit Webhook callback endpoint. |
For orders that originate in RBI’s platform, you will notice that most of these statuses are generated by our platform automatically as the order moves through the API actions described in the previous sections (pricing, committing, firing).