Building an integration with an EPOS

Overview

This guide provides a comprehensive overview of how a cloud connected EPOS company could integrate with Ordoo to synchronise menus as well as receive and mange orders.

We provide all of the APIs and webhooks to make integrating with Ordoo as easy as possible.

The above image shows all of the key components that make an Ordoo mobile ordering integration possible. Orders originate from the Ordoo App and should ultimately be shown to your customers EPOS systems.

Requirements

To ensure a great customer experience there are some requirements that need to be met for EPOS integrations.

  • You must receive orders in real-time. Orders should show on the EPOS terminal within 15 seconds of being placed. This can be achieved by utilising webhooks.

  • The EPOS terminal must implement an effective notification.

    It's important that operators are aware of incoming orders. The EPOS terminal should emit a sound or have a strong visual notification when an order is received or their are any pending or overdue orders.

  • The operator must be able to accept and decline orders. We provide the capabilities for orders to be progressed, this informs the customer that their order has been accepted and when it is ready. At minimum the operator must be able to accept and decline orders but an ideal implementation would also allow them to progress the orders to their ready and fulfilled states too.

1. Register an application

First you'll need to register your EPOS as an application. This will provide you the credentials to make API calls and authenticate a user is the next step.

For this integration you'll need the following grant types enabled:

  • read_menu

  • write_menu

  • read_orders

  • write_orders

  • read_stores

If you're software supports table ordering or you plan to add support later we would also suggest adding the following scope to create and manage tables:

  • write_stores

2. Authenticate a customer

For this integration you'll need access to the account of a mutual customer. To do this Ordoo uses OAuth 2.0, you can follow our guide to gain access tokens for these customers.

3. Synchronise the menu

Now that you've got access to the customers account you should provide automatically or provide a way to synchronise the products setup on your customers account with Ordoo.

We provide a series of APIs that relate to menu management, here are the APIs that relate to creating menu items and product options:

API Endpoint

Description

Create a collection

For creating a collection for products such as Coffees or Pizzas

Create a product

For creating a product such as an Americano or Margarita

Create a trait

For creating an product customisation such as Size or Toppings

Create a trait option

For creating an customisation option such as Large or Pepperoni

Each of these APIs returns the ID of the created object. You should keep a reference of this ID to allow for updating or the items.

4. Handle menu changes originating from your platform

When products are added, updated or removed you should ensure this change is reflected in Ordoo by adding, updating or removing the product via the API.

Resource

Create API

Update API

Destroy API

Collections

Create a collection

Update a collection

Destroy a collection

Product

Create a product

Update a product

Destroy a product

Trait

Create a trait

Update a trait

Destroy a trait

Trait Option

Create a trait option

Update a trait option

Destroy a trait option

5. Receiving Orders

To receive orders from Ordoo you can subscribe to the order.created event via a webhook. This will provide you the order details in real-time as soon as the order is placed on Ordoo. Follow the setting up webhooks guide to create your subscription.

At the point where you receive the webhook you should deal with notifying the venue via the EPOS till or kitchen display system. This should always include at minimum the following details:

  • The order ID

  • The first name of the customer who placed the order

  • The due at time of the order

  • The order notes

  • The order line items (products & trait options)

  • Any product notes

  • If the order is for eat in or takeaway

  • The table number if present

You should also store a reference of the order ID to allow you to progress the order in the next step.

6. Accept and progress orders

By this point the order should be accessible on the EPOS till or kitchen display system. A typical order would progress by flowing from pending to accepted to ready and finally to fulfilled.

However, a customer may cancel a pending order and a venue may decline a pending order.

Order Flow Paths

You must provide the mechanism for venue operators to accept and decline orders.

All orders should be progressed to their final state, however, progressing to ready and fulfilled can be automated by you at your own discretion.

Orders are progressed via the following API methods:

API Endpoint

Description

Automation permitted?

Accept an order

Accepting orders should only be initiated by a venue operator.

Decline an order

Declining orders should only be initiated by a venue operator.

Mark an order as ready

Alert the customer that their order is ready.

Fulfill an order

Mark the order as having been collected or delivered.

7. Recommended: Retrieve a list of active orders

Depending on your implementation you may want to request a list of currently active orders (at very least initially). For these orders you can use the GET /stores/{store_id}/orders endpoint with the optional query parameter ?active=true to filter only orders that should be visible on the EPOS or kitchen display system. Visit the API reference for more information.

8. Optional: Handle menu changes originating from Ordoo

Ordoo provides menu management, if you want changes made in Ordoo to reflect in your EPOS then you can subscribe to webhooks to be informed of these changes. Either way it should be made clear to the customer how their menu will be synchronised.

Resource

Create endpoint

Update endpoint

Destroy endpoint

Collections

Create a collection

Update a collection

Destroy a collection

Product

Create a product

Update a product

Destroy a product

Trait

Create a trait

Update a trait

Destroy a trait

Trait Option

Create a trait option

Update a trait option

Destroy a trait option

9. Optional: Setup table ordering

Ordoo provides support for table ordering, you can use the Ordoo API to create, update or list tables setup for an authenticated store.

To see how visit the Tables API reference.

🎉 Done

This should be everything you need to integrate as an EPOS provider. If you've got any queries then please get in contact with support@ordoo.co.uk.