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, because it confirms the order to the platform.
• 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 Lieferando delivery orders, the time refers to the final customer delivery time.

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

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.
• Lieferando: used directly as the customer delivery time.