Overview

eThor provides a single, robust API available to development partners. eThor API has been designed to allow partners to build a variety of functions into websites and mobile applications which are linked to in-store Point Of Sale (POS) systems.

There are several service endpoints defined in the Interactive Documentation which comprise eThor API. This API set is "RESTful.' There is no SOAP architecture or WSDL for the API. Requests may be made either for XML or JSON format. JSON format is recommended due to its smaller size and increased speed.

Partners access POS data stored in eThor's Cloud Platform of databases via eThor API, allowing them to pull and display store, chain, customer and menu information as well as build and submit orders to the POS systems. Certain API calls only query eThor’s databases in the cloud (requests for historical data, for example) while other real-time API calls (like placing orders) connect directly to the store POS systems.

An important concept to also understand is eThor’s Virtual Shopping Cart (VSC).  Due to the many varying ways that POS systems accept orders, eThor created a VSC to provide developers with a flexible tool that allows the order creation and modification process to be standardized across several different POS systems.  Essentially, the VSC is a buffer between your individual API calls and the POS.  You can “place items” into the VSC where they will be stored until you perform a submit call to send them down to the POS.  (after which point you may or may not be able to further modify the order depending on the POS)  This means that there are two “ID’s” for every order that is created and submitted to the POS:  eThor’s number (Ticket_ID or Order_ID) and the POS number (POS_Ticket_ID or POS_Order_ID).

For more information on the VSC and how to use it please refer to the use cases below.


Use Cases

eThor API supports several different use cases and customer flows…far more than we can list here.  We’ve chosen to highlight a few of the major ones below, but please contact us if you have questions as we know there are many other interesting use cases out there.

1 – Order Ahead

This is the typical web or mobile ordering scenario where your application allows a customer to view a menu, build an order, and then submit that order into the POS.  (with or without a payment)  Found mostly in delivery or takeout scenarios, you will be required to use several eThor API calls detailed below.

First you will need to look up your Stores by querying Chains, then Stores in our API.  Once you have the correct Store ID you can move on to pulling the menu.

Retrieving the menu:

menu calls

The above calls are used to retrieve a menu from a store.  You will need to develop some form of CMS in your application to manage the display of the menu to the customer.

Building an order:

order creation calls

Submitting the order to the POS:

order submit call

Once the customer has built the order and is ready to submit it to the store, you will need to either process a payment via a 3rd Party Payment Processor (like Stripe, Apple Pay, First Data, etc.) or submit the order as “cash”.  Approval reference numbers, UUID’s and Tokens can be sent down to the POS along with the order, however you CANNOT submit actual credit card numbers.

In this scenario the eThor Virtual Shopping Cart (VSC) is not used.  You are responsible for creating and managing your own shopping cart.  An order cannot be submitted to the POS until all items, discounts and payments have been added…so your software will need to store these actions until the customer is finished, then submit them to eThor as a fully developed order.

Note:  Once an order is submitted using the above calls it cannot be reopened or modified.


2 – Pay at the Table

This scenario is geared toward Fine Dining/Table Service/Bar environments where a server may or may not be part of the overall use case.  Customers are typically assigned a table or seat, and a corresponding ticket is created either by a server or by your application.  Once a ticket is present, the customer can order in stages and ultimately pay for their bill at the table using the functions below.

ticekts calls

Note that this scenario uses eThor’s Virtual Shopping Cart (VSC) which allows you to build a ticket with several items before sending it down to the POS.  Because of this, if you want new items to be pushed down to the POS you need to include a submit call after each new item is added.  (If you don’t the virtual ticket in eThor will be updated, but not the physical POS ticket)  It is also important to note that several items can be submitted to the POS at once.  For example, 3 menu items, 2 discounts and 1 payment can all be submitted at once.  

While this scenario sounds straightforward, there are countless ways to identify customers at tables (iBeacons, scanning QR codes on tables, entering ticket or table numbers into your app directly, etc) and the way the ticket is closed may vary depending on your use case.  (customer may pay via your app, or they still pay a server)  eThor provides you with the ability to extract a list of tables that are available in the POS, however it is up to you to create a way to manage and assign those to customers in your application.

Table information is found in the Stores section of the API as shown below:

stores-tables

3 – Cashier Present Payments

Found in QSR Restaurant and the majority of Retail segments, cashier present payments are just that – payments applied to orders which require a cashier to click a button on the POS machine to initiate the payment.  (aka event driven payments)

The current public eThor API does not facilitate these types of use cases however we have experience putting payment buttons on the POS with several strategic partners.  We are working to expand our API to allow these types of functions to be available publicly, but if you are currently building this type of application please contact us to discuss how we may provide a customer solution for you.


4 – Loyalty/Analytics

For applications which are not customer facing and only require the pulling of data from the POS, eThor API provides the following functions:

customers



Customer information is not available with all POS systems as some do not collect and store this data.  eThor API caches the customer information from the POS (if available) in the cloud, and provides it's own CRM-like capabilities allowing you to create customers and log transactions against those customers if you do not handle that yourself in your application.  Creating a new customer using eThor API only creates that customer on eThor's Platform, not in the POS.

order history

Using the GET/stores/{id}/orders call, you can enter various parameters to request the data you require.  (as detailed below)

order history parameters

It is important to note that when pulling historical information from eThor API your application will actually be access the eThor Cloud Servers, not the POS itself.  To eliminate latency and avoid slowing down the POS in store, eThor's Platform pushes order data up to eThor servers where it is accessed via the "GET" functions in eThor API.  This data is available in near real time. 

Note:  If you are pulling individual ticket information and are able to reference the ticket directly (as in scenario 2 above) then you can access the information directly from the POS in real-time.  Historical sales typically include several hundred records which is why we limit the ability to call the POS directly.