Mergeport Ordering is a channel manager for online ordering and delivery services. With a single interface we can forward all incoming orders from multiple service providers in a standardized format.

Access details and developer account

If not already done, contact us for a developer account. You will receive a unique siteId and apiKey.

Provider configuration

Typically, once you register with a service provider, they will provide you with some access details for their services, e.g. restaurantId or apiKey and apiSecret. You will need to forward each of those access details to Mergeport and we are ready to go.

Data flow

The connected online ordering services will synchronize orders with our platform. You can download all "active" orders [ status=receivedByProvider or status=canceledByProvider ] by calling /orders?filter=active. If you are using the HTTP Rest API, we would recommend to poll the orders with a delay of 1-2 minutes. Should anything go wrong during the download of the orders (aborted or missing connectivity), simply repeat the request until you have stored them, and then mark them as downloaded/read by calling /orders/{id} and setting [ status=fetchedByPOS ] to avoid duplicates. From that moment on, the order won’t be active anymore. To accept the order, you need to update the status to confirm the processing [ status=acceptedByPOS]. Upon confirmation, we will forward the information to the provider (if supported) and set the status to acceptedByPOS. This action confirms the processing. You can also accept the order right away and skip the fetchedByPOS state.

For MJAM direct integration: Additionally, in order to support the MJAM direct integration, the POS needs to send additional states to MERGEPORT:

• if the gastronomy takes care of the delivery : send inDelivery as soon as the order has been picked up by the rider. Note: there is no "delivered" status for vendor delivery in the MJAM integration.

• if the order gets picked up by the customer: send pickedUp as soon as the order has been fulfilled.

• If the MJAM delivery squad is in use: set the status to ready once the order can be picked up by the rider.

Cancelation workflow: if the provider cancels an already processed order, it is being added again to the active orders with the state canceledByProvider. This requests the POS to process the cancelation internally and set the order to canceledByPOS.

Please be aware that our interface can only forward and support as much information/features as the corresponding service provider provides. We do the best to standardize the information, but some data may be missing in the different cases.

Terms

In the following, we use different terms to explain the workflow/functionality of the API. Let us give you a quick briefing on how we use the mentioned terms:

• site: site corresponds to a restaurant
• POS item: article, menu item from the POS, e.g. "Spaghetti Bolognese"
• service provider: delivery platform, app, website that is connected to MERGEPORT

Prices and currencies

All prices are expressed as a structured object, with the currency code, e.g. "EUR" and the value in the atomic part of that currency, typically "cent". 3€ will be represented as 300.

Deposit: We forward the deposit fees we receive from providers to the POS systems. These fees are usually transmitted on an item-specific basis in the deposit field and are already included in the item price. However, not all providers send information about deposits (e.g., Just Eat Takeaway), and some providers (e.g., foodora) only send the total deposit for the entire order. In such cases, this total is included in the order.deposit field.

Order item structure

We use a flat list of order items items within the order object which, paired with the parentId, offers the flexibility to represent any hierarchical order data structure. Please note: the order item quantity is absolute, we also provide the relativeQuantity. If the customer has ordered three pizzas, all of them with 2 x cheese as modifier, this will result in two order items:

  id      quantity    relativeQuantity    description   singlePrice   rowTotal    parentId
  9a1     3           3                   pizza         700           2100        null
  3fc     6           2                   cheese        200           1200        9a1
                                                        total         3300

The absolut quantity makes sum checks easier, without having to reconstruct the whole order first. This is very helpful when analyzing data and logs for support cases.

Responses

Typically, our responses are being returned with the HTTP status codes 200 OK, 400 Bad Request, 401 Unauthorized, 403 Forbidden. We have three response types, you can easily check the response for the following fields:

• [data] - for read operations. The response contains an object or array of the requested data
• success - for generic operations. The success property contains a message describing the operation result.
• error - for minor errors. The error property contains a code and a message

You need to provide an apiKey as "Authorization" header for all API calls. The apiKey is provided by Mergeport in the registration process.

Authorization header

Every API call requires a valid apiKey in the "Authorization" header.

From this point on, you can choose to use the REST API, the WebSocket or a mixture of both. We recommend the usage of the WebSocket, as it enables a real-time communication and saves resources.

WebSocket API

WebSocket-URL: wss://socket.ordering.mergeport.com/v4

This API can give you push notifications of arriving orders or deliver the entire order upon arrival. All REST API functions can be used directly. To establish a connection with the WebSocket, you need to set a valid apiKey in the Sec-WebSocket-Protocol header. For example "'Sec-WebSocket-Protocol': '1f3a2007-8674-4496-9ccb-f1e9a8bebae5'". More details in the WebSocket-section.

• JavaScript example with protocol header parameter used for apiKey:

  // WebSocket Client endpoint to open the connection
  
  let exampleSocket = new WebSocket(url, apiKey);
  
  //Sample connect: let exampleSocket = new WebSocket("wss://socket.ordering.mergeport.com/v4", "1f3a2007-8674-4496-9ccb-f1e9a8bebae5");
  // you need to replace the sample key "1f3a2007-8674-4496-9ccb-f1e9a8bebae5" with your own provided **apiKey**
  
  // Event handler for the WebSocket connection opening
  exampleSocket.onopen = function (event) {
    exampleSocket.send("Here's some text that the server is urgently awaiting!");
  };
  
  // Event handler for receiving text messages
  exampleSocket.onmessage = function (event) {
    console.log(event.data);
  }
  
  // Event handler for errors in the WebSocket object
  exampleSocket.onerror = function (event) {
    console.log("Error ",event.data);
  }
  
  // Event handler for the close connection event
  exampleSocket.onclose = function(event) {
    console.log("WebSocket is closed now.");
  };
  
  // Function for sending commands to the server
  function sendAction(action, data = null) {
    // Construct a msg object containing the data the server needs to process the message from the client.
    var msg = {
      action: action,
      data: data,
      date: Date.now()
    };
    // Send the msg object as a JSON-formatted string.
    exampleSocket.send(JSON.stringify(msg));
  }
  
  // Send a test command for example get the version
  sendAction("version");
  
  // Finally close the connection
  exampleSocket.close();

• If setting a header is not possible in your environment, you can pass the apiKey as an url parameter accesstoken

  let exampleSocket = new WebSocket("wss://socket.ordering.mergeport.com/v4?accesstoken=1f3a2007-8674-4496-9ccb-f1e9a8bebae5");

  Websocket Events

  gotNewOrder Upon arrival of new orders, the Websocket sends an GotNewOrder-Action with the order

  {
  "action": "GotNewOrder",
  "data": {
    "orderId": "123456789",
    "providerId": "c933b71f-8efc-48ce-bd8c-630eb153ce10",
    "order": { **have_a_look_at_the_order_schema** }
  }
  }

  GetTable Upon arrival of provider request for table data, the Websocket sends an GetTable-Action with the table request

  {
  "action": "GetTable",
  "data": {
    "siteId": "c933b71f-8efc-48ce-bd8c-630eb153ce10",
    "tableId": "15",
    "providerId": "e5ec3c9a-325a-897e-a6b3-23a1953a6eee"
  }
  }

  WebSocket Requests

  The WebSocket supports the whole set of functionalities. Hence why you will find a "WebSocket" action in the description of every REST-endpoint. Just pass the WebSocket action as the "action" parameter in the WebSocket request (for example "GetOrders"):

  {
  "action": "GetOrders"
  }

  If you has to pas an url parameter {id} in the REST call you can pass them in the Socket-call as id:

  {
  "action": "GetOrder",
  "id": "8702f7e0-b2a7-452f-95db-ee69fd0aa3b6"
  }

  To serialize a requestBodyData inside the WebSocket-request, just add a data parameter:

  {
  "action": "SetOrderState",
  "id": "8702f7e0-b2a7-452f-95db-ee69fd0aa3b6",
  "data": {
    "state": "receivedByProvider"
  }
  }

  Websocket Responses

  PutTable Upon arrival of GetTable-Action, you should respond with an PutTable-Action with the table data

  {
  "action": "PutTable",
  "data": {
    "siteId": "c933b71f-8efc-48ce-bd8c-630eb153ce10",
    "tableId": "15",
    "providerId": "e5ec3c9a-325a-897e-a6b3-23a1953a6eee",
    "table": { **have_a_look_at_the_table_schema** }
  }
  }

  WebSocket Keep Alive

  In order to keep the WebSocket connection alive, the client is supposed to ping periodically. We recommend a period of 60s.

  {
  "action": "ka",
  "data": "ping" 
  }

  The maximum connection duration of the WebSocket API is 2h and cannot be increased. Hence why the client needs to implement a reconnect upon the closing signal.

  Request validation

  All requests will be validated. The following cases will lead to a validation error:

• Missing required properties

• Unknown properties in the request body

• Invalid data format.

  Important: date-time fields and parameters must be formatted as UTC ISO 8601 strings, e.g. '2000-01-01T10:10:10.123Z'.

Ordering operations allow the POS to synchronize orders and articles with ordering platforms. Ordering platforms include delivery services, Dine-In/Dine-Out apps & websites, table ordering services and discovery pages as well as websites. The Ordering API enables connected services to query the articles and menu items of the connected POS system and inject orders into the POS. As a feedback, the platforms receive status updates and preparation time changes.

Typically, the workflow is as following:

• Enduser orders within the ordering platform
• POS receives the list of active orders
• POS set the state of the active orders to "fetchedByPOS"
• POS processes the order and injects it into the workflow of the restaurant
• POS updates the state to "acceptedByPos" and continues to update along the processing