Mx Wolt Integrations Order Restaurant Guide
Order Restaurant Guide
This guide explains how to integrate Wolt's Order API using webhook notifications and pull-based order retrieval, ensuring your system can accept, track, and acknowledge orders in real-time.
Order Flow Overview
| Step | Description |
| 1 | Wolt sends a new order notification |
| 2 | Venue accepts order via Wolt Merchant App or POS (recommended) 2a Venue adjusts preparation time, if needed2b Venue acknowledges an order (if pre-order) |
| 3 | Wolt sends an accepted order notification |
| 4 | Partner pulls full order details via API |
| 5 | Partner pushes order to POS/system |
| 6 | (Optional) Courier approaching the venue |
| 7 | (Optional) Mark order as sent to POS via API |
| 8 | Venue marks order ready in Wolt App or POS (recommended) |
| 9 | (Optional) Courier pickup notification sent9 (Optional) Mark a takeaway order as delivered |
Webhook Notifications
New Order Notification
Wolt sends a webhook with a short payload when a new order is placed.
Example Payload
{
"id": "90f5c25cbbfb3d131a46e643",
"type": "order.notification",
"order": {
"id": "90f5be47fc97e11107f8a480",
"venue_id": "9a5c7e3102fe6a000c4b562b",
"status": "CREATED",
"resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
},
"created_at": "2021-07-19T18:20:12.378509Z"
}
Note: Validate HMAC signature in the header to confirm authenticity.
Order Accepted Notification
Sent after the venue accepts the order in the Wolt Merchant app.
Example Payload
{
"id": "90f5c25cbbfb3d131a46e643",
"type": "order.notification",
"order": {
"id": "90f5be47fc97e11107f8a480",
"venue_id": "9a5c7e3102fe6a000c4b562b",
"status": "PRODUCTION",
"resource_url": "https://pos-integration-service.wolt.com/orders/90f5be47fc97e11107f8a480"
},
"created_at": "2021-07-19T18:20:12.378509Z"
}
3. (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"
4. Order Ready Notification
Sent after the venue marks the order as ready in the Wolt Merchant app or using the ready API.
Example Payload
{
"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"
5. Courier Pickup Notification (Optional)
Sent when the Wolt courier picks up the order.
Example Payload
{
"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"
}
Order Retrieval
Use the resource_url from the webhook payload to retrieve the full order details.
curl -H "Authorization: Bearer {{access_token}}" \
https://pos-integration-service.wolt.com/orders/{{order_id}}
If resource_url is unavailable, construct the URL manually using the order ID.
Optional API Actions
Mark Order Sent to POS
Let Wolt know the order has been successfully pushed to your POS/system.
curl -X POST https://pos-integration-service.wolt.com/orders/{{order_id}}/mark-sent-to-pos \
-H "Authorization: Bearer {{access_token}}"
Best Practices
Verify webhook authenticity using HMAC signature.
Cache and reuse access tokens until they expire.
Avoid polling; rely on webhook triggers for events.
Handle retries idempotently in case of duplicate notifications.
Log and monitor webhook delivery failures.