7

Integration

Last Update 14 დღის წინ

POS & Platform Integration: Technical Overview Does MERGEPORT transmit tax information? Order Status Handling & Delivery Time Updates Add a Webhook notification How to Handle Pre Orders Properly

Order Status Handling & Delivery Time Updates

How to correctly update order states and delivery times across platforms

MERGEPORT

Last Update 14 დღის წინ

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

This article explains:

  • How to update an order state
  • How to send delivery-time updates
  • How to interpret possibleStateChanges
  • How selfDelivery and drivingTime affect delivery-time handling
  • 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.


Avoid frequent incremental updates.

Understanding possibleStateChanges

Each order contains something like:

This array tells the POS:
  • Which state changes are currently available
  • Whether a delivery- or pickup-time update is supported with that state
Rules:
  • Only send states listed in possibleStateChanges.
  • Do not assume that every platform supports the same states.
  • Do not send timeChange when the corresponding entry has timeChange: false.
  • The most important acknowledgement state is acceptedByPOS.
  • Some platforms may already have accepted an order but still require the POS to acknowledge it using acceptedByPOS.
  • If rejectedByPOS is not present, the order cannot be rejected through MERGEPORT.
The available states may depend on:
  • The ordering platform
  • The current order state
  • Whether the platform or restaurant performs the delivery
  • Whether the order has already been accepted by the platform
  • Platform-specific configuration
Always treat the possibleStateChanges of the individual order as authoritative.

Sending a timeChange

A time update must be sent together with a state:


Important


  • timeChange must be an absolute ISO-8601 UTC timestamp.
  • Do not send relative values such as +15 or 30 minutes.
  • If you want to postpone an existing time by 15 minutes, calculate and send the resulting timestamp.
  • Only send timeChange if the selected state has timeChange: true.
  • We recommend sending time updates mainly when accepting an order or starting preparation, provided the state is exposed by the order.
  • Avoid frequent incremental updates.


            If no delivery or pickup time was supplied with an ASAP order, send the newly calculated absolute timestamp.


                Combined example

                Delivery type and selfDelivery

                For delivery orders, deliveryInfo.selfDelivery indicates who performs the delivery:
                The values mean:
                • selfDelivery: true: the restaurant or its own delivery fleet performs the delivery.
                • selfDelivery: false: the ordering platform or its courier fleet performs the delivery.
                This distinction can change the meaning of timeChange.

                Platform-managed delivery

                For platform-managed delivery, the platform usually needs to know when the order will be ready for courier pickup.
                The POS can either send:
                1. The expected courier pickup time directly, or
                2. The final customer delivery time if drivingTime has been configured for the site.
                When drivingTime is configured, MERGEPORT calculates:
                Configure drivingTime through SetSiteSpecs:

                Restaurant self-delivery

                For restaurant self-delivery, the platform may require the final customer delivery ETA instead of a courier pickup time.
                The exact behaviour depends on the ordering platform. Always check possibleStateChanges and the platform-specific notes below.

                Platform-specific notes (status & time)

                Lieferando (Just Eat Takeaway)


                • timeChange represents the expected final delivery or pickup time.
                • MERGEPORT forwards the submitted time directly.
                • MERGEPORT does not subtract the configured drivingTime for Lieferando orders.
                • rejectedByPOS is currently not supported.
                • Time updates are supported only for states that expose timeChange: true.
                • Delivery-time changes may not be available when the Scoober courier fleet is used.
                • Always rely on the order’s possibleStateChanges.

                Wolt – platform-managed delivery


                For orders delivered by Wolt:

                • timeChange normally represents the expected courier pickup time.
                • If the POS sends the final customer delivery time, configure drivingTime.
                • MERGEPORT then subtracts drivingTime before sending the pickup time to Wolt.
                • Wolt limits adjusted pickup times to approximately 25 minutes after its original estimate.
                • MERGEPORT applies this limit before forwarding the update.
                • Wolt does not currently expose the MERGEPORT preparing state. Send the initial time update with acceptedByPOSwhen available.

                Wolt – restaurant self-delivery

                 For Wolt orders with:
                The submitted timeChange is treated as the final customer delivery ETA.
                In this case:
                • MERGEPORT does not subtract drivingTime.
                • When accepting a new self-delivery order, MERGEPORT forwards the delivery time through Wolt’s self-delivery acceptance flow.
                • If Wolt has already accepted the order, MERGEPORT updates the ETA through Wolt’s delivery ETA endpoint.
                • Whether the update is available is reflected by possibleStateChanges[].timeChange.

                Uber Eats – platform-managed delivery

                For Uber-delivered orders:
                • timeChange is forwarded as the expected ready-for-pickup time.
                • If the POS submits the final customer delivery time, configure drivingTime.
                • MERGEPORT subtracts drivingTime and forwards the calculated pickup time to Uber Eats.
                • Time updates are mainly supported with acceptedByPOS and preparing, depending on possibleStateChanges.

                Uber Eats – restaurant self-delivery

                The current MERGEPORT implementation uses the same drivingTime conversion for Uber Eats delivery orders regardless of the selfDelivery value.
                Therefore:
                • If drivingTime is configured and the POS submits a final customer delivery time, MERGEPORT subtracts drivingTime and sends the resulting ready-for-pickup time.
                • If the POS already sends a ready-for-pickup time, no drivingTime should be configured, otherwise the driving time would be subtracted again.
                • Always follow the individual order’s possibleStateChanges.

                Recommended integration logic

                Before sending an update:
                1. Find the desired state in possibleStateChanges.
                2. If the state is missing, do not send it.
                3. If timeChange is required, verify that the entry has timeChange: true.
                4. Determine whether timeChange represents pickup time or final delivery time for the platform and fulfilment type.
                5. Send an absolute ISO-8601 UTC timestamp.
                Example:

                Was this article helpful?

                0 out of 0 liked this article

                Still need help? Message Us