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.

Getting Started

Integrate Mergeport with a minimal setup:

1. Fetch open orders: GET /pos/orders?filter=active
2. Display orders in your POS
3. Accept order: PATCH /pos/orders/{id} with body:

   {
     "state": "acceptedByPOS"
   }

4. (Optional) Send further updates (preparing, ready, ...)
5. Use Webhooks, WebSocket, or Polling depending on your system architecture

Minimum requirement:

• Fetch orders
• Send acceptedByPOS

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 /pos/orders?filter=active. If you are using polling, we recommend an interval 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 /pos/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.

Order Lifecycle

Each order contains:

"possibleStateChanges": [...]

Only these states can be sent.

Required:

• acceptedByPOS

Rule: Only send states listed in possibleStateChanges

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.

Item Identification

Items can either be synced from the POS to the ordering platform (if supported) or managed directly on the platform side.

If items are managed on the platform, the POS item ID can be configured there. In this case, orders will include a posItemId, which serves as the primary identifier for items. As a fallback, orderItemId can be used as a secondary identifier.

Unknown Items

A POS must be able to handle items without a posItemId.

In these cases, recommended approaches include:

• Create item using name + price
• Apply a default tax rate
• Allow later mapping to an existing POS item

Important: Do not reject the order.

Additional Costs

additionalCosts is a free-text field.

Examples:

• Delivery
• Service Fee
• Tip
• Minimum Order Surcharge

Important:

• Values vary by platform
• Do not rely on fixed enums
• Handle unknown values gracefully

Date-time format

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

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.

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.

Mergeport supports three integration patterns:

• Webhooks (recommended for cloud systems)
• WebSocket (for persistent/local systems)
• Polling (simple / fallback)

Webhooks (Recommended)

Use webhooks if your POS is cloud-based.

• Configure webhook URL + secret in your integration
• Receive webhooks for new and/or canceled orders in real-time (same payload as GET /pos/orders/{id})
• No polling required
• Process orders via PATCH /pos/orders/{id}

Recommendation:
Use for all cloud systems.

Polling

Simple and universal fallback. GET /pos/orders?filter=active

• Periodic requests
• Higher latency depending on interval

Recommendation:
Use for simple setups or as fallback.

WebSocket

Use WebSocket for systems with a persistent connection (for example local servers, terminals, or always-on tablets).

• Connect to wss://socket.ordering.mergeport.com/v4
• Authenticate with the apiKey via Sec-WebSocket-Protocol or accesstoken
• Receive GotNewOrder events in real-time
• Process orders via PATCH /pos/orders/{id}

Recommendation:
Use for distributed or local systems without a public webhook endpoint.

How To

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. Use WebSocket for persistent or local systems, or as an alternative to webhooks when no public webhook endpoint is available. 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'".

• 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.

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