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

The MERGEPORT API documentation contains the full OpenAPI specification and the contracts for webhooks, WebSocket and order events. The following recommendations help you choose and implement your integration.

Recommended starting point: Standard Webhooks

For new cloud POS integrations, we recommend webhooks with Standard Webhooks. MERGEPORT sends complete, normalized orders to your public HTTPS endpoint. WebSocket suits continuously connected local systems without a public webhook endpoint; polling remains an alternative for simple integrations or reconciliation after connection problems.

Agree setup of the active POS connection with MERGEPORT and configure its accessDetails:

• webhookUrl: your endpoint for complete orders.
• webhookSecret: the shared signing secret.
• webhookSigningMode: "standard-webhooks": explicitly enables signing. Without this setting, existing legacy behavior remains in place.

Verify the webhook-id, webhook-timestamp and webhook-signature headers against the unchanged request bytes. MERGEPORT uses HMAC-SHA256 with the literal secret over {webhook-id}.{webhook-timestamp}.{raw-request-body}. In this mode, the secret is not transmitted in the Authorization header. Validate the timestamp and process repeated deliveries without duplicate bookings. A repeated delivery of the same message retains its ID and timestamp; account for the agreed retry window when checking timestamps.

Store the order before acknowledging HTTP receipt and handle subsequent updates to known orders. A successful HTTP response only acknowledges technical receipt. POS acceptance is a separate step using acceptedByPOS.

See POS webhook integration for setup, payloads and signature verification. The related article “Add a Webhook notification” describes the separate notification service and its signing; it does not replace setup of an active POS integration.

Subscribe to order events to keep the POS display current

Add an order-event subscription alongside new-order delivery so your POS can also display subsequent changes to status, courier information and fleet deliveries.

Event	Meaning for the POS display
order.statusChanged	The stored order status changed.
order.deliveryUpdated	Courier information from the ordering platform was updated.
order.deliveryFleetUpdated	A booked fleet delivery changed, for example its status, tracking or estimates.
order.posDeliveryFailed	The final technical order-delivery attempt to this POS connection failed; this is not a restaurant rejection.

In MERGEPORT Controller, select the Site and edit the active POS connection under Configuration. Set orderEventsUrl to a public HTTPS endpoint on port 443 without redirects, use a dedicated orderEventsSecret, and select orderEventTypes as a JSON array. Available fields depend on the POS definition; contact support if they are missing. An empty list or removing the event URL ends the subscription.

HTTP order events always use Standard Webhooks signatures with the separate orderEventsSecret. They contain identifiers and an event type, not a complete order. Verify the signature, promptly acknowledge receipt with HTTP 2xx and fetch the current record with GET /pos/orders/{id} when needed. For fleet events, retrieve the delivery with GET /pos/deliveries/{deliveryId}.

WebSocket connections can also opt in using subscribeOrderEvents after login; subscribe again after reconnecting. See the Order events documentation for details and examples.

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	Supplies POS items for menu synchronization or item mapping.
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. Send only offered transitions. fetchedByPOS does not replace subsequent acceptance with acceptedByPOS. The related article “Order Status Handling & Delivery Time Updates” explains platform differences.

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

Menu synchronization is available for Lieferando through JET Connect, Wolt, Uber Eats and foodora. We recommend it when the POS item master data is suitable for a high-quality online menu: clear names, complete descriptions, suitable images, maintained allergen information, choices and variants. Content quality is the deciding factor, beyond the technical ability to upload. Enablement and supported fields depend on the integration; older Lieferando connections have different capabilities.

Agree the appropriate workflow 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. AI-assisted item mapping is also in a testing phase. Contact support to arrange a trial, and review AI suggestions before applying them. 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

When synchronization is 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.

Optional: connect delivery fleets

For orders where the restaurant is responsible for delivery, you can connect a supported delivery fleet. Depending on setup, manual bookings or separately enabled automatic bookings are available. Configure the location, delivery partner and booking rules first.

Order and delivery statuses remain separate. The POS can track fleet deliveries using order.deliveryFleetUpdated and the Delivery API. See the related article “Connect delivery fleets with MERGEPORT” for setup, booking and cancellation.

Onboarding and headless management

Alongside order events, a separate callback reports a successfully verified platform connection. Configure providerLoginSuccessUrl in the POS accessDetails. The exact payload field is event: "providerloginsuccess"; it is not an orderEventTypes entry. Supported platforms are Wolt, Uber Eats, foodora and Lieferando, including JET Connect.

Use this callback to display connection progress in your own onboarding. It confirms a verified connection, not a ready menu, an open restaurant or a successful test order. Check the current connection status afterwards. The callback has its own delivery contract; the Standard Webhooks signing described above for order and order-event webhooks does not automatically apply to it.

Request Admin API access through support@mergeport.com. Authorized partners can manage Sites and platform connections from their own application, including creating, updating and removing them. This supports headless onboarding. MERGEPORT supplies the required permissions and Admin API documentation. OAuth integrations still require authorization by the operator.

The related article “Activate a MERGEPORT integration” describes setup in Controller.

Support & QA Resources

For developer access, test stores, AI mapping trials or questions about webhooks, order events and the Admin API, contact support@mergeport.com.