POS & Platform Integration: Technical Overview

This guide is designed for POS system developers integrating with MERGEPORT. MERGEPORT acts as a standardized middleware layer, unifying incoming orders from connected delivery and ordering platforms and forwarding them to your POS system.

API Documentation & Endpoints

You can find the full OpenAPI specification and WebSocket details in the developer documentation:

👉 MERGEPORT API Documentation

Key API Endpoints

The following paths are relative to the V4 API base URL. Use the active filter when retrieving active orders.

Method / Path	REST / WebSocket Action	Description
GET /pos/orders?filter=active	GetOrders	Retrieves active orders (status receivedByProvider or canceledByProvider).
GET /pos/orders/{id}	GetOrder	Retrieves a single order by ID.
PATCH /pos/orders/{id}	SetOrderState	Updates order status (e.g., to acceptedByPOS).
POST /pos/items	SetPosItems	Uploads POS item data (mandatory for platforms with menu sync).
DELETE /pos/items/{id}	DeletePosItem	Deletes a POS item from the MERGEPORT backend.

Technical Requirements

1. Order Types

Your POS system must process the order types supported by the respective ordering platform (e.g., delivery, pickup, or dine-in/table ordering). Since platform capabilities vary, specific fields are optional.

2. Order Status & Transitions

The POS system is responsible for controlling the lifecycle of the order. The valid status values in MERGEPORT are:

• receivedByProvider (order created on platform)
• fetchedByPOS (POS has confirmed retrieval; the order no longer appears in queries with filter=active)
• acceptedByPOS (order accepted and confirmed by POS; platform feedback depends on the integration and acceptance mode)
• preparing (meal preparation in progress)
• ready (order ready for pickup)
• pickedUp (order picked up by driver or customer)
• inDelivery (out for delivery by restaurant's own driver)
• delivered (order successfully delivered to customer)
• canceledByProvider (cancellation initiated by the platform)
• canceledByPOS / rejectedByPOS (cancellation/rejection initiated by the POS)

Within the order schema, the possibleStateChanges array defines the allowed status transitions for the POS.

3. Delivery Time Adjustments

If the field possibleStateChanges[].timeChange is defined as true for a state, the POS can send an updated delivery or pickup time in the SetOrderState request.

• Important: The timeChange parameter in the PATCH request is not a boolean. The API expects an absolute UTC timestamp formatted as an ISO 8601 string (e.g., '2000-01-01T10:10:10.123Z').

4. Handling Unknown Items

The POS must handle missing or unknown item IDs even when menu synchronization is enabled. Agree the workflow with the restaurant:

• Use stable IDs for matching and review uncertain matches manually.
• Map or create unknown items through an agreed process.
• Review fallback items and tax settings; a generic highest tax rate is not a MERGEPORT-verified solution.

Optional taxRate values do not replace POS tax handling. An absent field does not mean 0%.

Choose a menu management workflow

MERGEPORT supports menu synchronization for Lieferando through JET Connect, Wolt, Uber Eats and foodora. Agree one of the following workflows with the operator and platform:

• Synchronize the POS menu: The POS supplies products and menus through MERGEPORT. Maintain customer-facing names, descriptions, prices, images, allergens and options. Transferred fields depend on the menu channel and its mappings; for example, the current foodora menu transfer contains no allergen fields. A full upload can overwrite the existing platform menu.
• Maintain menus on the platforms: Configure matching POS identifiers/PLUs on the platform where available, or provide item mapping in the POS, for example for unknown items. Agree operation without menu synchronization with the platform; JET Connect requires enablement for this mode, while active Uber Eats menu synchronization can disable Menu Maker.
• Map items in the MERGEPORT Controller: Link imported platform products to POS items. The experimental Auto Mapper assists with matching; review its results. Item mapping does not change the customer-facing menu.

The related article “Menu Management: Synchronize or Maintain Menus Separately” helps with this decision. “Item Mapping for Online Orders” covers manual mapping and the Auto Mapper; “Menu requirements for Wolt, Uber Eats, foodora and JET Connect” explains how to prepare menu data.

Synchronize menu data from the POS

MERGEPORT supports menu synchronization for Lieferando through JET Connect, Wolt, Uber Eats and Foodora. When enabled and configured on the platform, the POS supplies menu data. Receiving orders without menu synchronization remains possible depending on the integration.

• Send menu changes using the /pos/items endpoint.
• Link variants or modifiers to the main item using parentIds.
• Define modifier groups using optionsList and their availableChoices in the upload payload.

Support & QA Resources

For test stores (e.g., Lieferando, Wolt, or Uber Eats sandbox access) or questions regarding WebSocket connections, contact support@mergeport.com.