Order Status Handling & Delivery Time Updates

Order status handling and delivery time updates are core components of every MERGEPORT integration.

This article explains:

• How to update order states correctly
• How to send delivery time updates
• How to interpret possibleStateChanges
• Platform-specific limitations

To update an order, issue a PATCH to the order endpoint:

Include state in the body.

Allowed states are always listed in possibleStateChanges of the order.

Example:

Rules

• Only use states listed in possibleStateChanges.
• possibleStateChanges is included in every order.
• Some providers internally map states differently for the end customer.
• The most important required state is acceptedByPos.

We recommend updating delivery times mainly when setting:

• acceptedByPos
• preparing

Avoid frequent incremental updates.

Each order contains something like:

• Which states are allowed
• Whether timeChange is permitted for that state

You may add timeChange together with a state if allowed.

Important

• timeChange must always be sent together with state.
• timeChange must be an ISO-8601 UTC timestamp.
• Usually, timeChange represents a difference from the originally calculated time (e.g. +15, +30 minutes).
• If the order was placed as ASAP and no reference time exists, send an absolute timestamp

Combined example

Lieferando (Just Eat Takeaway)

• Time updates are supported via API on selected states.
• Delivery time updates are NOT supported when Scoober (JET courier fleet) is used.
• In that case, Hybrid Mode may allow restaurant-side time control.
• The time sent represents the final delivery time for the end customer.
• “Reject” is currently not supported. Orders must be processed.

Wolt

• Time updates supported.
• Recommended mainly on accept and preparing.
• The time sent represents the courier pickup time.
• Alternatively, you may send the final customer delivery time.

If sending final delivery time:

• Configure drivingTime via SetSiteSpecs:
  https://ordering.mergeport.com/v4/documentation#operation/SetSiteSpecs
• MERGEPORT calculates pickup time.

Limit:

• Pickup time cannot exceed +25 minutes from the original estimate (soft validation)

Uber Eats

• Time updates supported.
• Recommended mainly on accept and preparing.
• The time sent represents the courier pickup time.
• Alternatively, you may send the final customer delivery time.
• Requires drivingTime configuration in DefaultPreparationTime via SetSiteSpecs.