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

The default authentication method is a Site apiKey in the "Authorization" header. Mergeport provides it during registration.

Authorization header

Use a valid Site apiKey in the "Authorization" header. Standard-signed webhook integrations may alternatively authenticate the selected POS write calls described in POS webhook integration. Do not combine both authentication modes. Other calls, including order retrieval, continue to use the Site API key.

Mergeport supports three integration patterns:

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

Webhooks (Recommended)

Webhooks are recommended for cloud POS systems. During the initial joint setup with MERGEPORT, agree which of the following optional features your connection uses. They are per-Site POS settings, not mandatory requirements for every partner.

Setting	Purpose
webhookSigningMode: "standard-webhooks"	Sign full-order webhooks with HMAC instead of transmitting webhookSecret. Also permits the selected signed POS API calls described below; regular Site API keys remain supported.
onlyAcceptedOrders	Forward orders after acceptance rather than at initial receipt. Suitable for an additional downstream receiver; another POS or the platform must provide acceptance where required. This setting does not accept orders itself.
forwardAllStatusChanges	Forward full-order updates for additional lifecycle states instead of just the usual order/cancellation delivery. This is separate from the minimal order-event subscription.
disableAutoRejection	For active POS delivery with scheduled retries, suppress the terminal MERGEPORT rejection/status update after retry exhaustion. Retries still stop; provider timeouts/cancellations, separate expiry checks and other POS connections remain possible. Arrange manual fulfilment when needed.
orderEventsUrl, orderEventTypes, orderEventsSecret	Subscribe separately to selected status, courier, fleet or terminal POS-delivery-failure notifications. Use a dedicated event signing secret; messages identify the affected order rather than sending it in full. See Order events.

Confirm the chosen settings with MERGEPORT before enabling them. Available Controller controls depend on the installed POS definition. In particular, the subscription is optional. With an event URL, supply orderEventTypes as an array, not a comma-separated string; an empty array unsubscribes. Without a subscription the fields can be omitted. Do not preselect events through defaults.

onlyAcceptedOrders and forwardAllStatusChanges currently control the notification-only webhook connection (dummyPOS); they do not change every active POS adapter's injection rules. With both enabled, additional status notifications remain enabled. Conversely, disableAutoRejection applies to the active POS retry flow, not this notification-only connection. Confirm the intended connection type during setup rather than copying all switches to every adapter.

Receive full normalized orders and acknowledge delivery separately from accepting/processing an order via PATCH /pos/orders/{id}. Order events are short change notifications, not complete orders. Events have no retries, replay or guaranteed delivery: avoid continuous polling as the primary mechanism, but retrieve current orders for reconciliation when needed. See POS webhook integration for setup, payloads, signing and delivery behavior, and Order events for subscription details.

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

Optional order-event subscriptions: after WebSocket login, send {"action":"subscribeOrderEvents","data":{"orderEventTypes":["order.statusChanged","order.deliveryUpdated","order.deliveryFleetUpdated","order.posDeliveryFailed"]}}. Notifications have action: orderEvent. An empty list unsubscribes; reconnect requires subscribing again. No replay; existing clients receive no new message types without opt-in. See Order events.

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.

Connection configuration changes

Each connection authenticates with the Site API key and reloads the current Site. Saving a disabled Site closes its ordinary POS connections; the existing Controller exception remains. Rotating the Site API key invalidates connections using the old key, including Controller connections. Reconnect with the current key; disabled or expired Sites cannot establish ordinary POS connections. Failed authentication returns HTTP 401 during the handshake. User-role changes do not revoke these independent Site-key connections. The existing message protocol is unchanged.

Both API documents share one product version. The version describes the code and documentation snapshot, not its production deployment status. The /beta documentation can preview changes while /v4 continues to serve a pinned production snapshot. Lambda versions identify the exact deployed function builds. Existing API paths do not change when the product version changes.

Prepared release snapshot; production promotion is tracked separately.

• Menu channels: shared optional menuTypes override per provider activation, otherwise POS-menu types and provider fallback. Wolt item fulfillment, separate Uber delivery/pickup variants with matching incremental updates and independent comparison state, JET delivery/collection menus and foodora catalog variants. Deliveroo remains a shared catalog. Existing channel configurations require a reviewed compatibility setup before rollout; incoming orders and POS item identities are unchanged. Uber requires delivery and a common catalog; distinct fulfillment assortments use item availability while categories, options and menu hours remain shared. Item/category menu membership is preserved for JET and foodora and Wolt methods are resolved per item. No automatic provider service activation or old-menu deletion.

• Wolt menu channel: item availability updates also update matching option values, including nested choices, through the existing updateMenuItems flow. Choice lists and prices remain unchanged; partial provider failures are reported through the existing channel status and retry policy.

• Internal diagnostics: technical notification attempts gain structured operation/error-code grouping while preserving existing error and administrative Site emails. No POS/provider API contract changes. Deployment and monitoring-rule configuration are required to use the new events.

Prepared release snapshot; production promotion is tracked separately.

• POS acceptance: a missing receipt no longer blocks acceptedByPOS. requireReceipt remains a request to supply a receipt; submitted receipts are still validated.

• Foodora: direct restaurant deliveries send the existing order_picked_up callback on delivered; customer pickup remains supported and logistics deliveries do not send this callback on delivered.

• Foodora cash orders: a valid collectFromCustomer above grandTotal determines the payment amount and amountToPay. Paid/card orders and equal or lower collection amounts remain unchanged; item prices are preserved and no fee position is invented.

• Compatibility change: discount position allocations are now returned exclusively as discounts[].orderItems instead of discounts[].items. Consumers of the previous field must update their access. Historical allocations are translated on reads without a database migration; order items, prices and payment totals are unchanged.

• Internal notifications: user creation no longer sends userCreate to Make; SES password-setup emails remain unchanged. Retained Site/user-update notifications await one bounded Make delivery attempt with safe correlated diagnostics. Delivery failure does not roll back saved changes; no automatic retries are introduced.

• POS menu allergens: additive A1-A6 cereal and H1-H8 nut subcodes in the existing allergens string. Uber/Wolt export localized specific names; JET Connect exports existing detailed enums. Existing codes remain compatible. Configure the allergen mapping and perform a full menu upload; no stored-item migration or price/order changes.

• Menu channels: JET, foodora and Deliveroo V3 retain automatic menu changes received during an unresolved upload and submit the latest menu after confirmed success. Availability follows the new menu; manual conflicts and uncertain-result safeguards remain unchanged.

• JET Connect: explicitly identified platform deliveries no longer produce full-address validation warnings when the provider omits address fields. Merchant delivery and unknown delivery ownership retain existing checks; supplied address data is preserved.

• Order reads: removed the internal five-second item-hydration cutoff from POS/provider order retrieval; complete, strongly consistent pagination is retained. Webhook/background hydration keeps its existing bound; infrastructure timeouts still apply.

• WebSocket: connection lookup uses one Promise-based AWS request instead of mixing callback and Promise execution. Current Site authorization and message contracts remain unchanged.

Prepared release snapshot; production promotion is tracked separately.

• Authentication: password setup/reset sessions correctly recognize the Gateway-routed user PATCH method. Restricted access remains limited to setting the authenticated user's password; normal login and existing account permissions are unchanged.

• Menu channels: Wolt/JET preserve every known allergen group in mixed code strings such as AF,G. JET adds optional explicit vegan/vegetarian label mapping for products and modifiers; existing channels require enabling the field and a menu upload. Prices and order processing are unchanged.

• Uber menu channel: optional allergens and dietary-label mappings expand POS allergen codes to menu-language names and export vegan/vegetarian declarations. Existing channels require explicit field links and a full menu upload; additives, prices and incoming orders are unchanged.

• Uber orders: removed zero-quantity options retain their removal instructions without adding their former unit prices to item totals, in both supported payload formats. Selected options, order/payment totals and existing stored orders are unchanged.

• Uber menu channel: full uploads apply the selected activation's allowSpecialInstructions setting to item-level instructions. False/missing disables them; true enables them. Existing menus require a full upload; incoming order notes and price/availability-only updates are unchanged.

• Uber menu channel: honor explicit option multiselect using group-scoped quantity limits, preserving box totals, prices and defaults. Missing flags retain existing behavior; existing menus require a subsequent full upload.

• Order item reads: full-order reads, status updates and POS retry payloads load every item page consistently; missing embedded webhook items are loaded before sending. Item-read failures no longer return successful partial orders. Already completed status/provider actions are not rolled back. Incoming order writes, subscription, retry and webhook ordering policies are unchanged.

• Uber menu channel: automatic changes are coalesced by the scheduler with cooldown and Retry-After handling. The optional updateMenuItems function supports mapped price and availability updates and defaults to off. Automatic choice requires both functions explicitly onChange with matching mappings; item-only mode never implicitly uploads a full menu. Automatic synchronization is deferred rather than sent inside the item request.

• Uber menu channel: disabled products and modifiers are correctly marked sold out; explicitly enabled items clear prior suspension. Existing remote menus require a successful subsequent upload. No price, identifier or option-relationship changes.

• Channels: track provider processing separately from HTTP acceptance. Correlated JET/foodora callbacks and Deliveroo V3 job checks update the latest upload result; dependent availability changes wait for confirmed success. Wolt and uncorrelated Deliveroo V1 responses do not claim publication confirmation. No automatic upload retry or online configuration migration.

• POS order-state responses and history: optional successful providerResults distinguish acknowledged, asynchronously accepted and explicitly already-applied actions. Errors and warnings retain their existing behavior. Main status-webhook success enriches the original history entry after local persistence, without extra events or callback retries. No configuration change or migration required.

• JET Connect: optional per-country previous order key supports coordinated inbound webhook credential rotation. Outgoing requests continue to use only the current key; HMAC and restaurant checks remain unchanged. Remove the temporary previous key after the sender has switched. No automatic configuration changes.

• POS/provider API: optional DB-configured delivery, takeaway and inHouse lifecycles expose effective providerTransmission flags and fixed-English descriptions. Local time changes remain independent of transmission. Existing definitions retain legacy fallback; complete stateTransitions replace the Main timeChangeStates list while preserving order restrictions. Definitions are activated manually; no automatic migration.

• JET Connect: after required POS acceptance, local progress follows legacy Lieferando, independently of the ETA switch. With allowDeliveryTimeChange enabled, merchant deliveries also receive legacy-compatible time-change flags for preparing, inDelivery and inDelivery to delivered, in addition to acceptance. Later time changes use the separate JET ETA endpoint, never repeat acceptance, and preserve the previous state/time on failure. No same-state updates or ETA for JET courier delivery/collection. JET-side pilot enablement remains required; acceptance logic and other providers are unchanged.

• Admin API: PATCH /admin/site/{id}/providers/{providerInstanceId} updates one existing provider activation without replacing the entire provider list. Omitted settings are preserved, accessDetails merges by immediate key, and supplied nested objects/lists replace their field. Existing validation, permissions, Restaurant ownership and channel lifecycle apply; concurrent edits of submitted fields return a conflict. Existing Site PATCH/add/remove behavior is unchanged. No migration or new configuration required.

• Deliveroo V3 menu upload: accept upload-URL responses containing upload_url and version without an echoed menu ID. Publication retains the requested menu; contradictory echoed IDs remain rejected. No configuration or data migration required.

• Deliveroo availability: incremental updates and explicit maintenance use the menu-scoped V1 endpoint with the configured menuId (default main), matching API-uploaded menus. Payloads and item status semantics are unchanged; no new setting or migration is required.

• Deliveroo menu bundles: component prices now use parent-item ITEM overrides with the bundle ID and section context_id, without a competing MODIFIER override. Standalone prices, PLUs, ordinary options and POS inputs remain unchanged; no data migration or new setting is required.

• POS catalog: optional bundle object with optional partySize, using existing optionsList sections and explicit choice prices. Deliveroo exports bundles and standalone component products with context-specific prices; ordinary items and other providers retain their behavior.

• POS catalog: optional hidden boolean, currently interpreted only by Deliveroo availability synchronization. True takes precedence over enabled; false clears hiding while preserving any stock restriction. POST replacement and PATCH partial semantics remain unchanged. Ordinary stock synchronization remains incremental POST.

• Deliveroo menu uploads: optional menuApiVersion "3" uses the same menu through S3 upload and a version-specific publication job. Missing configuration retains V1; item availability and order flows are unchanged. Initial upload acceptance does not establish completed publication; the correlated processing result is tracked separately. No automatic upload retries, fallback or definition import.

• Deliveroo menu schedules: resolve existing PosAvailability menu assignments, with channel-specific overrides. Convert exclusive POS period ends to inclusive Deliveroo minute boundaries; reject overlapping or incomplete scheduled mealtimes unless a single fallback menu covers the gaps. No automatic channel configuration changes.

• Deliveroo menu channels: optionally export existing POS menu names, descriptions and cover images, plus explicit item dietary labels. Existing saved channel links require opting into the new mappings; the default mealtime remains when no menus are mapped. POS option groups accept an optional localized description. No new required fields or automatic configuration migration.

• JET configuration: set Provider.accessConfig.apiUrl and orderStatusApiUrl before rollout. Existing menu, availability and status services retain their hosts but now read the central configuration; no runtime URL fallback. Acceptance with ETA uses the status service, separate ETA updates use apiUrl. Add the optional allowDeliveryTimeChange descriptor to Provider.accessDetails and enable it per Site activation; countryCredentials owns country-specific brandSlug values.

• JET Connect: optional per-activation customer delivery ETA on acceptedByPOS for merchant deliveries. Requires JET pilot enablement and central country-specific configuration. ETA transmission remains disabled by default and uses the existing acceptance flow; autoAccept ETA failures retain acceptance and the previous time with an HTTP 200 warning.

• Uber Eats courier updates: correctly resolve stored provider connection settings for optional pickup-ETA lookups; webhook status processing remains available when enrichment fails.
• Operational diagnostics: identify Lieferando login and venue-status failures with safe Site/restaurant context without logging provider response bodies.

• POS signed requests: correct Beta REST stage detection; production signatures and regular Site API-key authentication remain unchanged.

• POS order status documentation: describe existing optional rejection reason/notes and tablet-based Deliveroo synchronization failures; normal missing-PLU handling is unchanged.

• Provider/POS configuration metadata: dependsOn and dependsOnAll additionally support explicit isSet/equals conditions; existing boolean-name conditions remain supported. optional fields can be omitted without defaults. Event subscription fields can be conditionally required by their URL. No automatic subscription or definition migration.

• POS documentation: expanded webhook setup and optional order-event subscriptions, moved the webhook guide next to Orders, and separated developer test-order and manual channel-sync documentation without changing endpoint behavior.

• Admin Site reactivation: safely releases interrupted read-only cleanup checkpoints; provider/payment changes report explicit cleanup errors instead of misleading reload conflicts. Possible partial deletion remains blocked for support review. No automatic restoration or migration. Nightly cleanup compares eligibility marker values independently of DynamoDB field ordering, allowing eligible unblocked runs to proceed; existing blocked checkpoints remain stopped.

• Uber Eats orders: aggregated total_fee is displayed as Zusätzliche Gebühren (DE), Additional Fees (EN), or Costi aggiuntivi (IT), using the Site language. Applies to both incoming order formats and newly processed orders only; amounts, taxes, tips and totals are unchanged.

• Main SP API: generic providers configure timeChange support per target state via Provider accessConfig.timeChangeStates. Missing/empty disables time changes; the hardcoded allowlist is removed. Existing enabled definitions must be updated before rollout. Dedicated adapters keep their rules; preorders and explicit restrictions take precedence. Target-state semantics also apply to delivered after preparing.

• POS webhooks: additive Site/POS/provider routing headers and optional signed authentication for POST /pos/items and PATCH /pos/orders/{id}. Existing standard-webhooks mode and webhookSecret enable these incoming calls too; no additional setting is needed. Existing API-key and outgoing signing behavior remain unchanged. Promote the POS handler before the authorizer; reverse that order for rollback. Documentation includes WebSocket order-event opt-in.

• Main SP API: customer.mobilePhone is optional for all order types (inHouse, pickup and delivery). Supplied phone numbers remain strings; no configuration or migration is required.

• Foodora customer pickup: pickedUp remains the completion state; inDelivery/delivered are no longer offered or accepted (STATUS_CHANGE_NOT_ALLOWED), including orders with older stored transition lists. No new ready prerequisite, callback change or data migration. Compatibility restriction: notify affected POS partners before rollout. Foodora deliveries and other providers are unchanged.

• Uber Eats older V2 orders: nested selected and removed modifiers are now included using the existing V1 flat item/quantity convention. Existing direct items, order/payment totals and acknowledgements remain unchanged; newly visible nested modifiers may need POS mappings. No historical order migration.

• Fix: order retention loads correctly in the Lambda/Webpack bundle, restoring affected order writes. Six-month deadlines and cleanup rules are unchanged; no automatic historical backfill is started.

• POS orders: optional parentGroupId identifies the immediate Uber Eats modifier group or Wolt POS option group. Existing item IDs, mapping, prices and quantities are unchanged, including Wolt posItemId whitespace. Missing identifiers remain omitted; identifiers are provider/menu-scoped, not globally unique. No configuration or migration required.

• Administration: optional emailed initial password setup (48 hours) and public password reset (30 minutes), with one-time restricted access and automatic normal login after saving. Normal password login remains supported. Requires the PasswordAccess table, SES template/sending permissions and Controller integration. Password changes revoke previous User sessions; Site/POS API keys are unchanged.

• POS developer test orders: add split-payments, additional-costs, discount and fully populated self-delivery examples. Existing samples stay unchanged; self-delivery can trigger configured fleet automation after acceptance and requires the same explicit frontend risk confirmation.

• POS API: optional one-shot order-event webhooks and per-connection WebSocket subscriptions for status, platform courier, fleet and terminal POS injection failures. No retries or guaranteed delivery; old sockets and order delivery stay unchanged. Requires POS definition/configuration updates. Internal terminal-failure notifications reuse the existing internal notification receiver. Optional courierInfo separates pickup ETA from customer delivery time; Wolt pickup ETA no longer overwrites deliveryInfo.deliveryTime.

• POS API: GET /pos/restaurant adds credential-free providerDetails summaries with provider and activation IDs, stored names and existing pending/verified connection status. Reads do not trigger verification; existing response fields and configuration writes are unchanged.

• Main SP order ingress: optional payments array accepts split payments using the existing payment entry structure. A nonempty array wins; missing/null/empty falls back to deprecated payment. Each array amount is used independently without changing the order total; legacy single-payment amount behavior is preserved. Receipt and cash-tender metadata follow the selected payments. Native provider adapters and Site billing are unchanged.

• Order retention: StandardOrders, their line items, raw provider orders and order-owned delivery jobs expire after six calendar months. Cleanup is asynchronous and sends no provider/POS cancellation. Old order retrieval, raw callback lookup and duplicate detection are no longer guaranteed beyond retention. Shared mappings and catalogs remain; delivery offers retain their short expiry. Requires native table TTL and a separately approved metadata backfill for existing records; older pinned writers do not assign the new deadlines.

• Wolt Drive scheduled bookings repeat the quoted delivery timestamp in the delivery request. ASAP booking behavior is unchanged; no configuration or data migration is required.

• POS order discounts: optional merchant campaign externalId and possibly incomplete position allocations (internalId, discounted quantity and total position discount). Existing amounts, payments and discount rows are unchanged; ambiguous details are omitted. Supported data varies by provider and API format. Main SP order ingress accepts the optional external campaign ID. No migration required.

• POS order acknowledgement: JET Connect now supports local fetchedByPOS acknowledgement before acceptedByPOS, retaining the original acceptance deadline. Direct acceptance remains supported; fetched acknowledgement does not notify JET of acceptance. Expired JET acceptance attempts return HTTP 410. The scheduler now correctly includes fetchedByPOS orders for all providers in existing timeout and age-limit handling. No migration or new provider callback.

• Admin Site/payment APIs: optional server-derived paymentRevision detects stale payment/access snapshots. Both PATCH paths retain the original snapshot during conditional writes and retries. Legacy requests without a revision remain accepted and cannot detect changes made before the initial server read. Revision-aware clients must reload and recompute after HTTP 409 PAYMENT_STATE_CONFLICT. Deploy Ordering first, then revision-aware payment clients; no stored revision migration.

Additive configuration release and Controller integration fix; production promotion is tracked separately.

• Controller integration: siteUpdate notifications after Site PATCH, payment PATCH and Wolt authorization now carry the complete saved Site snapshot in data.after, subject to the existing Controller filtering, rather than only changed fields. Payment API responses remain reduced; database writes still update only their owned fields. No data migration or API-path change.

• Uber Eats configuration: optional per-activation allowSpecialInstructions (default false) controls the provider special-instruction request setting at activation and on configuration changes. Incoming instructions and item-level menu settings are unchanged. Add the field to the stored Provider definition manually; failed external updates return the existing post-save provider warning.

• Foodora menu channels: catalogSync enables menu synchronization independently of directIntegration. Existing API payloads and order processing remain unchanged; no data migration or new configuration fields are required.

• Internal User API: optional boolean userSpecs.betaTester and userSpecs.readOnly can be saved by authorized management. Omitted PATCH fields preserve existing values; missing flags mean false. Self privilege expansion remains forbidden. No new environment routing or order-flow behavior.

Prepared release snapshot; production promotion is tracked separately. Includes the 4.3.1 maintenance fixes below.

• Internal Admin API: optional Dealer userSpecs.manageSameLevelRole (default false) delegates management of sibling Dealers, their POS children and Sites under the same parent. New Dealer creation uses the shared parent; only superior management can grant/revoke delegation. Parent-user and cross-hierarchy management remain excluded. Existing onlyOwn/shared-Site rights and authorized impersonation responses remain unchanged; impersonation inherits target permissions. No data migration or POS/order-flow changes.

• User-management hardening: Site WebSocket contexts cannot act as User logins, even with matching email metadata. User scopes and existing hierarchy checks remain required; authorized User responses and internal self-registration stay compatible. Authorization diagnostics use credential/user fingerprints, safe concrete IDs, operation/method and rejection reason without raw tokens or email addresses.

• Site WebSockets: saving a disabled Site revokes ordinary POS connections, preserving the Controller exception. API-key changes revoke old-key connections including Controllers. Reconnect and every business message check the freshly loaded Site and current key, including expiry for ordinary POS connections; rejected authentication returns 401. Existing message formats and independent user-role behavior remain unchanged.

• Internal user management: explicit editable fields, parent scope/role/cycle validation, admin-only licensing and preserved SDK inheritance. Profile/password/company updates remain available to self and authorized management; self privilege expansion and self activation changes are rejected. Technical/unknown fields are ignored. Concurrent target changes return 409 and require reload. Self onboarding cannot choose parent, expanded access or licensing. Independent POS WebSocket connections remain unchanged.

• Breaking internal Admin API cleanup: removed legacy Dealer REST/WebSocket operations and the obsolete importV3Sites/migrateSiteUserDetails commands. Dealer/dealeradmin user roles and parent-based permissions remain. dealerId is retired from User/Site inputs and schemas; existing stored attributes are not migrated or deleted. New-Site internal notifications identify the owner, direct parent and creator instead. Dealer tables remain retained infrastructure pending separately authorized cleanup.

• Internal administration: strengthen Site ownership and inherited read-only checks. User PATCH accepts an omitted role without changing it and ignores echoed server-managed token fields; invalid bodies/roles return 400. No credential rotation or hierarchy migration.

• JET Connect: percentage-discount and free-item promotion names follow Site standardLanguage (German, English, Italian), retaining product names and amounts. Applies to newly processed orders without additional database reads.

• Wolt Drive cash collection and recipient delivery-fee share now require a positive outstanding CASH payment. Fully prepaid/zero-cash orders omit cash in quotes and bookings. Existing cash quotes for these orders must be requested again.

• Wolt Drive: safe request diagnostics identify provider HTTP errors, known error codes, validation fields and cash quote calculation step. Existing error envelope and retry/booking behavior remain unchanged; no configuration migration.

• Provider cancellations: document existing terminal canceled output consistently for REST orders, active POS webhooks and WebSocket notifications. It does not require POS acknowledgement or create new polling work; canceledByProvider retains its actionable meaning. Direct cancellations clear hasWork only after a bounded consistent check with concurrent-work guards. Repeated terminal cancellations remain canceled. Internal work revisions require coordinated handler promotion; no manual Site migration.

• Foodora: four-/five-digit postcodes with locality suffixes normalize to zip plus city (e.g. Salzburg (Aigen)), preserving address information without duplicating the city. Blank postcode uses deliveryAreaPostcode as fallback; unknown formats and comments remain unchanged. No configuration or stored-order migration required.

• JET Connect: star/whitespace-only last names normalize to null. Masked-only names are excluded from the formatted address; the required firstName value and real/partially masked names are preserved. Existing orders are not rewritten.

• Lieferando and JET Connect: labelled address supplements populate floor, apartment and entrance regardless of label case or whitespace. Compatibility change for JET: successfully assigned unambiguous address labels are removed from comment (null when empty); POS clients must display floor, apt and entrance. Unassigned text, the full formatted address and notes remain intact. Lieferando retains its original comment. No stored orders are rewritten.

• Channel configuration: concurrent removal or switch-off cannot be undone by a late channel setup; configuration writes check the current activation and preserve unrelated Site fields.

• JET Connect mapping catalogs: explicit and initial imports use the public Lieferando menu via shopUrl, scoped to the JET activation. Imports update catalog information without replacing assigned POS targets; they do not reconcile menu identifiers with supplied order PLUs.

• Speedy / JET activation: one-time transfer of existing Lieferando POS mapping targets, copied in resumable conditional batches before activating the new connection. Existing JET connections and Speedy receipt behavior remain unchanged. Ambiguous legacy ownership or conflicting targets block activation; bounded catalog reads and copy deadlines require separate handling for larger catalogs. No new provider definition setting required.

• Internal Admin API: targeted provider/add and provider/remove operations preserve other activations. Shared Site PATCH commits Site, Restaurant mappings and removed channels atomically; concurrent changes return a conflict. External disconnection is best effort with explicit warnings. Repeated removal is a no-op; uncertain adds must be checked before retrying. No automatic migration.

• Internal Admin API: reduced Site payment list/detail and field-scoped PATCH for commercials, enabled and expirationDate. Admin may write all three payment fields on either Site PATCH; dealer/dealeradmin only enabled; POS none. Role-excluded fields are silently ignored. Site write permission remains required. Admin full-object saves can still overwrite payments. Omitted existing ownership is preserved. No migration required.

• Wolt Drive: optional localized customer SMS and dependent handshake PIN, driver-visible orderReference, and scheduled preorder quotes using the customer delivery time. Stored fleet definitions require optional sms/handshakePin metadata. POS createTestOrder adds fleet-preorder (four hours ahead) and delivery instructions. Main SP address.comment now takes precedence over the legacy formatted-address comment fallback.

• Foodora Logistics Delivery: dynamic preparation-time adjustment on existing acceptedByPOS/preparing/ready transitions when supplied by the provider. Successful state changes can return an optional time-change warning; rejected adjustments preserve the previous ETA and record the attempt. Rider waiting events use provider-neutral platformUpdates fields. Incoming delivery times no longer require an address; missing delivery time can use pickup plus configured drivingTime. No new POS endpoint or same-state updates. The SetOrderState success text typo is corrected to successful; clients should use HTTP status, not exact message matching.

• Fleet definition metadata documents optional min/max/unit for numeric configuration inputs. The Wolt recipientDeliveryFeePercent template supplies 0–100 and %. Add these descriptors to existing stored definitions manually; runtime validation remains unchanged.

• Neutral delivery fleets: optional signed quote/confirmed-booking workflow selected by activation bookingMode (default direct). parcelCount is optional; dispatches include main items and outstanding CASH collection details. Quotes are bound to delivery data and expire via TTL. Automatic quote bookings require maxPrice; direct automation retains explicit unpriced consent. Enable quotes in the stored definition only when its webhook implements the contract. Existing activations and delivery identities remain unchanged.

• POS createTestOrder: fleet-cash and fleet-cash-insufficient samples exercise cashToExpect and Wolt cash collection. Existing prepaid samples remain unchanged. These persisted merchant-delivery orders can trigger configured automation on acceptance; use a sandbox fleet.

• Wolt Drive: opt-in cash collection per Site fleet activation with recipientDeliveryFeePercent (0–100). Only outstanding CASH payments plus the recipient delivery-fee share are collected; existing payments remain unchanged. Quotes and deliveries expose cashCollection. Add the two configuration descriptors to the stored Wolt fleet definition manually and confirm Wolt cash contract support. Default remains prepaid-only.

• POS/Main SP orders: optional paymentInfo.cashToExpect preserves explicitly announced cash tender from Lieferando POS API, Wolt and Main SP payment.cashToExpect in cents and currency. Existing payment amounts, totals and notes are unchanged; no migration or configuration required.

• Wolt Drive: derive parcels from main order items and their quantities, names and available unit prices; omit bag_count. Wolt Drive no longer requires parcelCount and ignores it when supplied; neutral webhook fleets accept it optionally. Item changes invalidate quotes; quotes obtained before this change must be refreshed. Existing deliveries and prepaid-only behavior remain unchanged.

Prepared maintenance release; deployment and production promotion are tracked separately.

• JET Connect: newly normalized orders derive missing article identifiers using the legacy Lieferando exact-name algorithm. Supplied PLUs are unchanged; ID-less choices follow the legacy parent/sibling rules. Existing orders and mappings are not rewritten; no cross-provider mapping migration is enabled.
• Lieferando: concurrent alive notifications update their owned timestamp fields without replacing unrelated Site configuration.
• Order reads: reduce database round trips and reuse complete item reads; existing response and state semantics remain unchanged. POS activity writes are throttled to once per 30 seconds.
• Build: split generated validation schemas without changing validation rules.
• POS test orders: Berlin customer coordinates and explicit time-change support for Development orders.
• No new fleet quote, cash-collection or parcel behavior is included in this patch.

Prepared release snapshot; production promotion is tracked separately.

Added: delivery fleets

• Site-scoped delivery-fleet activations, separate from ordering providers and POS integrations. Existing order acceptance behavior remains independent from delivery booking.
• Neutral signed webhook dispatch and delivery callbacks, plus Wolt Drive quotes, booking, tracking and manual cancellation. Capabilities depend on the configured fleet.
• Optional automatic booking after acceptedByPOS, with provider/instance filters, Wolt price limits, pickup-time rules and parcel-count policies. Neutral automatic booking requires explicit consent to unpriced dispatch.
• Optional cancellation attempts for automatically booked deliveries when their order is cancelled or rejected, subject to fleet support and its cancellation window. Order cancellation does not guarantee delivery cancellation.
• Additive deliveryAutomation order status/history for queued work and cases requiring attention. Delivery state remains separate from order state.

Included fixes

• Neutral fleet callbacks default to https://ordering.mergeport.com/v4 when the callback-base environment variable is missing or empty; Beta requires an explicit override. Dev remains separately configured. Existing delivery callback snapshots and Wolt webhook registration are unchanged.

• Neutral fleets accept readySoon for booking and retry. Automatic delivery observation continues when automatic cancellation is disabled, without resending bookings. Single-item reads preserve optional taxRate, including zero.

• Lieferando pin_at_doorstep is normalized as a card payment, preserving the provider method as its brand and the incoming paid status. Unsupported payment methods now fail transformation instead of producing an invalid paymentInfo value.

Integration and operational notes

Fleet APIs are exposed through the POS API; their appearance in this shared history does not add fleet booking operations to the ordering-provider API. Existing integrations remain manual unless automation is explicitly configured. Preserve activation IDs and revision-based configuration updates. An existing delivery reservation, including an uncertain booking outcome, must not trigger a second booking.

Setup requires fleet definitions, Site activation credentials and the relevant callback configuration. Automation additionally requires the StandardOrder queue index and scheduled worker; retaining database tables alone does not keep automation running when deploying older code. No automatic definition import or existing-Site migration is performed.

Further changes included in this release

• POS mapping catalog now always reads stored activation-scoped ProviderMappingItems, with Site-wide, provider and activation filters, consistent activeOnly and full filtered counts. Legacy rows are no longer read or migrated by catalog requests; restart old cursors. GET /pos/mappings behavior is unchanged but its documentation is internal-only; POST remains public.

• JET Connect: identical item rows now combine into one position with summed quantity. Complete item content, including modifiers and notes, must match; regular and promotional items remain separate. POS clients may receive fewer positions with larger quantities; amounts and article IDs are unchanged. Existing orders are not rewritten.

• JET Connect: address fields containing only asterisks or whitespace are treated as unavailable in newly normalized orders, including formatted addresses. Real and partially masked content is preserved.

• Provider verification: compact internal state after confirmation; diagnostic details are logged instead of retained per target. Success-webhook entries are removed on delivery or final failure, with exhausted failures logged. Existing verbose records are cleaned gradually; public pending/verified status, retry timing and configuration-change verification remain unchanged.

• JET Connect display-name fallback: missing/blank or technical JET Connect channel names no longer replace the legacy Lieferando name. A recognized shop URL or concrete channel takes precedence over country (DE/AT: Lieferando; NL: thuisbezorgd). Existing stored orders and item mappings remain unchanged.

• JET Connect payment compatibility: paymentType/brand now match legacy Lieferando (CARD/credit, CASH/cashier, doorstep CARD/pin_at_doorstep). Existing paid status and amounts remain unchanged. Original payment_method/tender_type are retained in additionalInternalInfo as jetConnectPayment JSON. Clients matching the former composite JET brand must adapt.

• Disabled Sites: server-managed disabledSince tracks continuous deactivation (unknown legacy dates start at first observation). From 72 hours until before 144 hours, one-time bounded maintenance marks pending orders timedOut locally and clears hasWork after a completed scan; only unfinished work retries within this window, without provider/POS/fleet notifications. Reactivation resets the period. After twelve months of continuous deactivation, bounded nightly maintenance permanently removes owned data and the Site; an explicitly reviewed historical cohort has a one-time eligibility exception. No external cancellation is sent. Disabled/expired POS authorization now stops before activity writes. The existing Controller exception is unchanged.

• WIX: optional per-activation splitGroupedModifiers expands clear grouped xN option descriptions into individually mappable toppings. Default off; normal modifiers, prices and totals remain unchanged. New stable group/name IDs do not inherit old grouped mappings. Add the optional field to the stored WIX definition before configuring the Site.

• Neutral delivery fleets can report optional WGS84 courier positions independently of status updates. The latest position is exposed to the POS and removed at delivery completion; Wolt Drive remains unchanged.

• Legacy Lieferando courier deliveries no longer offer POS time changes. Confirmations retain the original provider timestamp instead of applying a new ETA; JET Connect is unchanged.

• POS and Main SP item APIs: options is deprecated in favor of optionsList. Empty/missing lists fall back to legacy options without removing the old field; populated lists win. POST normalizes submitted data; PATCH preserves existing lists and requires clearing both fields to remove all groups. Item outputs, update webhooks and menu channels use the same selection. Foodora development-channel fix: addPrice is relative to the modifier base price, not an absolute price; recheck/resync existing test menus.

• Active POS connections: optional disableAutoRejection (default false) removes exhausted injection retries without changing order status or notifying the provider. Retry timing/counts are unchanged. Separate expiry/cancellation flows and other POS connections remain independent; stored POS definitions need the optional setting metadata.

• POS catalog: PATCH /pos/items updates only explicitly supplied fields of existing items, with per-item bulk results and complete stored items for synchronization. POST remains replacement/upsert. Nested objects replace the field; nullable null and empty values have explicit clearing semantics. No migration or provider configuration change required.

• POS order-state errors: additive machine-readable origin/type and actual upstream HTTP status, preserving existing messages, HTTP codes and receipt validation shapes. No new receipt requirement. Before JET production rollout, its HTTP 410 expiry error now uses error.message instead of a bare error string (same text and status).

• Lieferando POS API: pizza-half labels supplied as side-dish IDs are preserved in order-item names. Existing mapping IDs, prices and quantities are unchanged.

• POS catalog: optional numeric taxRate (0–100 percent, including zero) in item uploads, individual updates and responses. Optional menu-channel mappings for Wolt, JET, Uber Eats and Deliveroo; existing saved channels require enabling the new field link. Gross prices are unchanged; no default tax rate is inferred.

• POS API: createTestOrder creates pickup, on-premises, delivery and fleet samples via the normal order pipeline. Requires a configured Development provider on the authenticated test Site. Fleet samples distinguish automation eligibility; acceptance can trigger paid deliveries. No automatic acceptance.

• Main SP: optional deliveryInfo.selfDelivery now preserves explicit delivery ownership in normalized orders, including fleet test orders. Missing values retain the vendorDelivery fallback; explicit false is not overridden.

• Documentation: restored Main SP order cancellation under Orders and added the neutral delivery-fleet dispatch/signature/status-callback contract to the provider documentation; no runtime behavior change.

• Beta clients: fleet definitions require an existing Site and its API key via GET /pos/delivery-fleet-definitions. The redundant GET /admin/delivery-fleets endpoint has been removed; admin login tokens are not accepted by the POS endpoint.

• JET Connect preserves the legacy Lieferando display-name spelling for the matching shop platform. Optional deliveryInfo.phonePin/pickupInfo.phonePin expose masked-phone codes; localized PIN notes preserve compatibility with existing POS clients.

• Provider-login success events include the Site standardLanguage when present, frozen across delivery retries.

Baseline before the delivery-fleet release. Earlier changes were not recorded systematically under distinct product versions; no retrospective release dates or complete change lists are asserted here.

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