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; mandatory to notify platforms)
• 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 (stornation initiated by the platform)
• canceledByPOS / rejectedByPOS (stornation/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

For platforms without item synchronization (such as Lieferando), the POS system must be prepared to resolve unknown item IDs:

• Match incoming items by name or assign them to a generic fallback item with a default tax rate.
• Allow manual item mapping in the POS immediately upon receiving the order.
• Automatically create the unknown item using the incoming name and price, applying the highest local tax rate for safety.

Menu Synchronization (Where Supported)

For integrations that support menu syncing, the POS system acts as the "Source of Truth."

• Send menu changes using the /pos/items endpoint.
• Link variants or modifiers to the main item using parentIds.
• Define selectable options and groups using 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.