Mx Integrations Order Retail Guide
Here's a simplified, structured version of the Wolt Retail Order Integration Workflow — specifically for manual acceptance and fulfillment using the Wolt Merchant App):
Retail Order Flow Overview
| Step | Description |
| 1 | Order appears in Wolt Merchant App |
| 2 | Venue staff accepts order manually |
| 3 | Items are picked in App Lite (substitutions handled) |
| 4 | Order marked ready in App Lite |
| 5 | Wolt sends "Order Ready" webhook |
| 6 | (Optional) Courier pickup webhook sent |
| 7 | Partner pulls updated order details from Wolt API |
| 8 | Partner sends order to internal systems |
| 9 | Wolt sends "Order Delivered" webhook |
Key Webhook Notifications
1. Order Ready Notification
Triggered after venue staff completes picking and marks the order as ready in the App Lite.
Payload Example
{
"id": "90f5c25cbbfb3d131a46e643",
"type": "order.notification",
"order": {
"id": "90f5be47fc97e11107f8a480",
"venue_id": "9a5c7e3102fe6a000c4b562b",
"status": "READY",
"resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
},
"created_at": "2021-07-19T18:20:12.378509Z"
}
2. (Courier) Courier approaching the venue
Sent when courier is approaching the venue
Example Payload
{
"id": "90f5c25cbbfb3d131a46e643",
"type": "courier.notification",
"order": {
"id": "90f5be47fc97e11107f8a480",
"venue_id": "9a5c7e3102fe6a000c4b562b",
"resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
},
"courier_details": { "courier_pickup_eta": "2025-03-29T11:16:43.000Z" },
"created_at": "2021-07-19T18:20:12.378509Z"
3. Courier Pickup Notification (Optional)
Sent when the Wolt courier picks up the order.
Payload Example
{
"id": "6630d3034b4f2f54c43c727a",
"type": "pickup_completed.notification",
"order": {
"id": "90f5be47fc97e11107f8a480",
"venue_id": "9a5c7e3102fe6a000c4b562b",
"resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
},
"details": {
"is_pickup_completed": true
},
"created_at": "2021-07-19T18:20:12.378509Z"
}
4. Order Delivered Notification
Sent when the courier marks the order as delivered.
Payload Example
{
"id": "90f5c25cbbfb3d131a46e643",
"type": "order.notification",
"order": {
"id": "90f5be47fc97e11107f8a480",
"venue_id": "9a5c7e3102fe6a000c4b562b",
"status": "DELIVERED",
"resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
},
"created_at": "2021-07-19T18:20:12.378509Z"
}
Pulling Final Order Details
The order_ready webhook does not include full order contents. Use the resource_url to fetch complete order data — including any updates from substitutions or missing items.
curl -H "Authorization: Bearer {{access_token}}" \
https://pos-integration-service.wolt.com/orders/{{order_id}}
Important Notes
Order modifications (substitutions, missing items) are reflected in the API response when you pull order details after the READY status.
Treat webhook notifications as triggers and always pull full order data before processing internally.
Ensure your system handles out-of-order events, retries, and validates against duplicate processing.