Order Status Handling & Delivery Time Updates

How order states and delivery times are handled across platforms

MERGEPORT normalizes orders from different platforms and provides them to POS systems through one unified API. Order status changes and delivery-time updates are sent through the same order endpoint:

PATCH /orders/{orderId}

Example:

{
  "state": "acceptedByPOS",
  "timeChange": "2026-07-06T18:45:00.000Z"
}

Updating order states

The new state is set in the state field.

{
  "state": "pickedUp"
}

Important rules:

• Only use states that are listed in the order's possibleStateChanges.
• possibleStateChanges is included with every order.
• The most important state is acceptedByPOS: it confirms acceptance by the POS. Whether a callback is also sent to the platform depends on the integration and its acceptance mode.
• Platforms may use different internal state names and state logic.
• State changes can affect customer-facing order views, courier logic, and platform workflows.

Understanding possibleStateChanges

Each order contains the possible next state changes, for example:

"possibleStateChanges": [
  { "state": "acceptedByPOS", "timeChange": true },
  { "state": "ready", "timeChange": false }
]

This means:

• state: This state may be sent as the next update.
• timeChange: Indicates whether a time update is allowed together with this state change.

If timeChange is false, do not send a time update with that state change.

Delivery time updates

Delivery time updates are sent through the timeChange field.

Important rules:

• timeChange must be sent together with state.
• timeChange must be an absolute ISO-8601 timestamp.
• timeChange is not a minute delta.
• The time should be sent in UTC.

Example:

{
  "state": "acceptedByPOS",
  "timeChange": "2026-07-06T18:45:00.000Z"
}

We recommend sending time updates mainly with these state changes:

• acceptedByPOS
• preparing

Avoid frequent or repeated time updates.

Unified delivery logic with drivingTime

To make delivery-order behavior more consistent, the integration setup can include defaultPreparationTime.drivingTime:

SetSiteSpecs in the MERGEPORT API documentation

The POS can then generally send the final customer delivery time as timeChange for delivery orders.

MERGEPORT uses this time differently depending on the platform:

• For Wolt and Uber Eats courier deliveries, MERGEPORT can calculate the required pickup or ready time from it.
• For Wolt selfDelivery, the final customer delivery time is sent directly to Wolt.
• For delivery orders on the previous Lieferando integration, an allowed time update refers to the final customer delivery time. JET Connect currently does not support time updates through MERGEPORT.

Important:

• For pickup or takeaway orders, the relevant time is the customer pickup time, not a delivery time.
• Only send timeChange for state changes where possibleStateChanges[].timeChange is true.

Platform-specific behavior

Wolt

For Wolt, distinguish between Wolt courier delivery and selfDelivery.

Wolt courier delivery

For Wolt courier deliveries, Wolt generally expects a courier pickup time.

If the POS sends a final customer delivery time and defaultPreparationTime.drivingTime is configured, MERGEPORT subtracts the driving time and sends the calculated pickup or ready time to Wolt.

Example:

• POS sends final delivery time: 19:00
• drivingTime: 20 minutes
• MERGEPORT sends to Wolt: 18:40 as the pickup or ready time

Note: Wolt limits pickup-time adjustments. The calculated or sent pickup time cannot move arbitrarily far away from the original Wolt estimate.

Wolt selfDelivery

With Wolt selfDelivery, the merchant or the merchant's own driver handles delivery.

In this case, Wolt expects the final customer delivery time. MERGEPORT does not subtract drivingTime.

This means:

• The POS sends the final customer delivery time.
• MERGEPORT sends that time directly to Wolt.

Uber Eats

MERGEPORT generally sends a ready or pickup time to Uber Eats.

If the POS wants to send a final customer delivery time, defaultPreparationTime.drivingTime should be configured. MERGEPORT then subtracts the driving time and sends the corresponding ready or pickup time to Uber Eats.

Example:

• POS sends final delivery time: 19:00
• drivingTime: 20 minutes
• MERGEPORT sends to Uber Eats: 18:40 as the ready or pickup time

Lieferando / Just Eat Takeaway

Build new connections around JET Connect, which is intended to replace the previous interface as the standard. Existing restaurants migrate after coordination.

JET Connect

JET Connect currently does not support delivery or pickup time updates through the MERGEPORT API. Its available state changes have timeChange: false. Do not send a time update or a preparing state unless offered in possibleStateChanges.

fetchedByPOS only acknowledges receipt by the POS. It must still be followed by acceptedByPOS; receipt does not extend the acceptance deadline. In posAccept mode, MERGEPORT reports successful POS acceptance back to JET. In autoAccept mode, this technical acknowledgement happens when the order arrives, without waiting for POS acceptance. These modes do not determine customer-facing acceptance on the Orderpad.

Existing older connections only, until migration

The following time rules apply only while your restaurant still uses the previous Lieferando interface. Do not carry these rules over to JET Connect when migrating.

For Lieferando delivery orders, the time usually refers to the final customer delivery time.

For pickup orders, the time refers to the customer pickup time.

No drivingTime conversion is required for Lieferando.

Notes:

• Delivery time updates are generally supported, but may be limited depending on the Lieferando setup.
• Certain Lieferando or Scoober setups can have restrictions.
• Time updates should be sent as early as possible, ideally with acceptedByPOS or preparing.

Unaccepted orders and timeouts

Unaccepted orders eventually run into a timeout.

Platforms have their own acceptance windows. If an order is not confirmed in time, it may be automatically rejected or canceled from the customer's perspective.

For that reason, always send acceptedByPOS as soon as possible.

Recommendation for POS integrations

For a consistent implementation:

1. Retrieve the order or receive it by webhook.
2. Check possibleStateChanges.
3. Confirm the order promptly with acceptedByPOS.
4. If a delivery time should be updated:
   • Send timeChange only when it is allowed for the state.
   • Send an absolute ISO-8601 timestamp.
   • For delivery orders, ideally send the final customer delivery time.
   • For Wolt or Uber courier deliveries, configure defaultPreparationTime.drivingTime so MERGEPORT can calculate the pickup or ready time.

Example

The POS confirms a delivery order and sets the final customer delivery time:

{
  "state": "acceptedByPOS",
  "timeChange": "2026-07-06T18:45:00.000Z"
}

MERGEPORT processes this time depending on the platform:

• Wolt courier: converted to pickup time if drivingTime is set.
• Wolt selfDelivery: forwarded directly as the customer delivery time.
• Uber Eats: converted to ready or pickup time if drivingTime is set.
• Previous Lieferando integration: used directly as the customer delivery time, where allowed for the state.
• JET Connect: no time update; omit timeChange.