Introduction

Background

Delivery Hero has been offering POS Integrations globally for more than 3 years. With more than 100 integrations and 1000s of branches connected worldwide, Delivery Hero is the market leader integrating with the food space.

Our API is flexible, which means you can code in a language that makes sense with your core systems or POS infrastructure. We send you orders and you translate them on your side so that it makes sense. Before you can jump into coding, you need to get the right credentials to talk to our systems. Developers should sign up below.

Next Steps:

  1. Get Credentials & Middleware URLs
  2. Provide us an endpoint to send orders to
  3. Test orders from a test restaurant that we will provide
  4. Develop plugin
  5. Rollout

Overview

We offer integrations through two different flows. Direct integrations are only done with permission from the Delivery Hero platform on a chain per chain level.

Indirect

Indirect means that a physical restaurant will have a tablet with a dedicated Delivery Hero app for managing orders. Additionally, the POS system will also receive those orders through our POS module upon order acceptance.

On the image below, components for a typical indirect setups are shown.

Indirect Flow

Orders are pushed to plugins after they are accepted on the Restaurant App of Delivery Hero. As a simplified example, the flow for dispatching an order until it reaches the POS Alpha will be:

  1. A customer places an order at a restaurant for Alpha Chain on a Delivery Hero platform (e.g. Foodora).
  2. Foodora pushes that order to the restaurant tablet app. The order at this stage contains either expectedDeliveryTime, riderPickupTime or customerPickupTime.
  3. The restaurant manager accepts the order.
  4. The order is pushed to the middleware which forwards it to the plugin using the dispatch endpoint.
  5. The plugin performs as many calls as needed in order to dispatch the order to the API of POS Alpha.
  6. The Order reaches POS Alpha.
  7. At this stage, if POS Alpha has auto-acceptance, the order is synced on both systems (Foodora and POS Alpha). Otherwise the restaurant manager must accept the order on POS Alpha as well.

As illustrated above, each chain communicates with Delivery Hero resources only through a plugin. The goal of this plugin is to adapt communication between our middleware and the chain API. The goal of the middleware is to integrate plugins with Delivery Hero platforms. Hence, every POS system requires the implementation of a plugin.

Important Info
  1. The POS is only storing information on orders when accepted, the restaurant app is still handling the orders from start to finish.
  2. Multiple Delivery Hero platforms are supported and will be sent to the one POS ID.
  3. One integration should work globally on all Delivery Hero platforms.
Implementation

Communication between our Middleware and plugins will happen only via REST/HTTP. Please check the following documentation to understand how the plugin will have to work:

  • Notice that not all endpoints must be implemented. Many will not.
  • Order Dispatch flow documentation (seen below): the plugin developer has to decide which flow to implement based on the capabilities of their POS system.
  • Only the order_accepted status update is allowed to be performed by the plugin (using this endpoint). All order status updates (cancellation, etc.) should be performed on the Delivery Hero Restaurant App.
  • You are hosting the plugin

Direct

Direct means that physical restaurant will not have a Delivery Hero application. Instead, the restaurant will only use the POS system which is currently in the shop.

Direct Flow 1

As illustrated above, each chain communicates with Delivery Hero resources only through a plugin. The goal of a plugin is to adapt communication between our middleware and the chain API. The goal of the middleware is to integrate plugins with Delivery Hero platforms. Hence, every POS system requires the implementation of a plugin.

As a simplified example, the flow for dispatching an order would be:

  1. Customer places an order at a restaurant for Alpha Chain on a Delivery Hero platform (e.g. Foodora).
  2. Foodora pushes that order to the Delivery Hero middleware.
  3. The middleware pushes that order to the Alpha plugin using the order dispatch endpoint described here.
  4. The Alpha plugin does as many calls as needed in order to dispatch the order on the Alpha chain using the Alpha chain API.

Direct Flow 2

Important Info
  1. Multiple Delivery Hero platforms are supported and will be sent to the one POS ID.
  2. One integration should work globally on all Delivery Hero platforms.
Basic Needs

In order to apply a POS as Primary integration, Delivery Hero requires certain functionalities on the plugin and POS side to ensure the end customer receives the same expected service level as when a tablet is present:

  • Ability to manually accept and reject an order at the restaurant.
  • When accepted, a delivery time is sent (non-foodora) can be via algorithm or manually sent.
  • When rejected, reason is given (based on the platform).
  • When an order is ready to be picked up by the driver, Delivery Hero is notified via manual button push or algorithm (non-foodora).
  • If the POS is unreachable by the POS provider/restaurant, an unreachable status is sent to Delivery Hero (backchanneled using POS ID, not the order). Vice versa, when POS is back online a reachable status is sent.
Additional Needs

In some cases additional requirements are need and based on the platform's support capabilities. The more a POS integration supports, the greater access it has to the Delivery Hero network and restaurant base.

  • Ability to mark that the restaurant is closed/busy for X amount of time.
  • Ability to mark certain items on the menu are unavailable or available again.
  • Ability to mark that the ETA of a certain order is delayed.
Implementation

Communication between our Middleware and plugins will happen only via REST/HTTP. Please check the following documentation to understand how the plugin will have to work:

  • Notice that not all endpoints must be implemented.
  • Order Dispatch flow documentation (seen below): the plugin developer has to decide which flow to implement based on the capabilities of their POS system.

Remote Codes

Delivery Hero can update menus on our side with corresponding IDs for products defined on the chain or POS side. This is flexible and can be defined completely based on your requirements. Should your menu be updated or changed, you would be expected to ask for this field to be updated as well.

Example:

  • Large Cheeseburger: 6YLI-89
    • Extra Tomatoes: 6YLI-89-56HH
    • No Lettuce: 6YLI-89-90RR
    • Swiss Cheese: MONDAY

Plugin

The following describes the building of the plugin, which translates incoming orders to a language understandable by the POS system.

URL Schema

The url of the plugin must be behind a secure https certificate.

Authentication

The Middleware sends a JSON Web Token (JWT) in the Authorization header on all requests to the authenticated area of this API. The Middleware generates a JWT with a shared secret, which the plugin uses to validate the signature of the JSON Web Token.

Example of a JWT signed with the secret 123:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzZXJ2aWNlIjoibWlkZGxld2FyZSJ9.VKb-yT2Zz2e4j7R5ssXzU0Mj5MrQ7yxP1H1YRPFmlVANhOYwadSk-5GepYUBz19KASD0QjwLTWtOKLR63Y_R9g

The shared secret will be provided by the Delivery Hero Integrations team.

More info at: https://jwt.io/

Error Responses

If a request to the POS provider fails or is not available, the plugin must return a 502 with the error code POS_ERROR.

On the other hand, internal application errors on the plugin should return a 500 with the error code INTERNAL_ERROR.

Middleware

The Middleware forwards orders from Delivery Hero to the plugin developed by the 3rd party.

URL Schema

The middleware URLs are divided into the following and you will receive the relevant ones when you apply for credentials:

  • World
  • Asia
  • Staging (all instances)

Authentication

Oauth2 - the client credentials flow is used for authentication https://tools.ietf.org/html/rfc6749#section-4.4. After a successful login the plugin is given a JWT as a bearer access token. That JWT should be used on all subsequent authenticated request in header Authorization: bearer the-token-you-got.

Please keep in mind the token expires after the time specified in the login response expires_in.

Error Responses

Notice that if the payload to the Middleware fails or is wrong it will return a 400 with the error code INVALID_REQUEST.

On the other hand, internal application errors should return a 500 with the error code INTERNAL_ERROR.

Plugin Order Dispatch

How you receive an incoming order.

  • Authenticated

Order

There are two kinds of orders, delivery and pickup orders. A delivery order has a delivery object containing data about the delivery address details unless it is an order delivered by a Delivery Hero entity, while a pickup order contains data about the pickup details.

Based on the HTTP status returned, the Delivery Hero order status is saved differently:

  • 202 - The order status does NOT change on the Delivery Hero side. The plugin has to call the middleware to update the order status (to the update-order-status endpoint), and if no request is sent to the middleware, the order will become overdue and automatically cancelled. So as an example, the flow would be:
  1. The middleware calls this endpoint to dispatch an order.
  2. The plugin dispatches the order and returns a 202 http response code.
  3. When the status of the order changes then the plugin calls the middleware.
  • Others: Order will be marked as dispatch_error on Delivery Hero. A call center agent might handle the order and it could be dispatched again. This response code has the same effect as if you send the dispatch_error as a status change. The message given on this response will be available to the platform.

Order Dispatching

Plugin Order Status

Endpoint for managing order statuses on the POS side. Right now it is only used to get cancellation requests from the platform, logistics or by the user via the Delivery Hero software.

  • Authenticated

Update POS Order Status

Middleware Login

This is used to authenticate into the middleware.

Login

Middleware Update Status

Status updates are used for integrations where no software from Delivery Hero will be used. This means an order is sent from a platform and then directly pushed to the POS.

  • Authenticated

Update Order Status

Initially, after the order was sent from the Delivery Hero system, this endpoint has to be called by giving any of the following statuses: order_accepted, dispatch_error, order_rejected.

dispatch_error should be used whenever there is some issue on the POS provider side (or on the plugin side), which does not allow the order to be dispatched, although some platforms are able to resend the order in some cases (e.g. POS provider service down).

On the other hand, order_rejected should be used whenever the POS provider explicitly rejects the order. This would mean that the order will NOT be able to be dispatched again.

After this step, supported status transitions are:

From -> To

Restaurant Delivery order_accepted -> order_picked_up, order_delivered

Restaurant Pickup order_accepted -> order_delivered

DeliveryHero Delivery order_accepted

Final statuses for which no further transitions are accepted: dispatch_error, order_rejected, vendor_cancelled, customer_cancelled, order_delivered

POS Reachability Status

This endpoint is used to notify Delivery Hero when POS device gets online or offline. As result, respective restaurant will be taken on or offline on each of the DH platforms.

  • Authenticated

Update POS Reachability Status