Restaurant iPad-free integration

Use case

Local and global enterprise restaurants have several venues and varying degrees of delivery order volumes. Such enterprise partners also work with more than one delivery partner, which leads to multiple devices needed at the venue.

By using the iPad-free implementation partners can manage all your Wolt operations from a single device or POS.

APIs to use for this integration

Phone support required

iPad free restaurants must receive phone support from the Wolt local market team.

Not all restaurant partners qualify for phone support. Please check with the Wolt local team to confirm if an enterprise restaurant qualifies for phone support.

API	Endpoint
Order API	Order status webhook notification
Order API	Get order
Order API	Accept order
Order API	Reject order
Order API	Mark order ready
Order API	Confirm pre-order
Order API	Mark order sent to POS
Menu API	Create menu
Menu API	Update menu items
Menu API	Update menu options
Venue API	Get venue status
Venue API	Update venue online status
Venue API	Update venue opening times

Authentication

The Wolt Marketplace APIs use the bearer token authentication method. To authenticate your requests, include your access token in the Authorization header of each request. Replace {{access_token}} in the example requests with the actual access token obtained through the OAuth 2.0 flow.

To retrieve the token, you need to setup OAuth 2.0 authentication.

Other requirements

Webhook server

You will need to have a webhook server to be able to receive order status webhook notifications. These notifications will inform you status of the order.

For Wolt to know where to send the status notifications we need to know the URL of your webhook server. Inform your Wolt account manager the URL of your webhook server.

Webhook server security

The partner must provide a client secret that must be different from the API key, cryptographically random and at least 128 bits in length. This will be used to sign the webhook body using HMAC-SHA256.

Wolt signs the request by generating a signature from the request body, using the client secret, and sending it alongside the request.

Wolt signature specification

Notifications are signed with HMAC-SHA256.
String format for the signature is HEX.
The signature is placed to the WOLT-SIGNATURE HTTP request header.
The secret key for generating the signature from the request body is the client secret

Both the API key and client secret should be stored and provided to the application securely. Knowledge of either value may allow an attacker to act as the partner. The design should allow either value to be changed easily in the event they would leak. In particular, the values should not be stored in source code or plaintext configuration files.

Wolt signature example

Client secret: example-hmac-sha256-wolt

To generate the signature of the body, use HMAC-SHA256 with the client secret provided to Wolt. Generate it from the request body (i.e. the notification), and compare it to the value in the wolt-signature header.

POST /webhook

{
   "id":"68656c6c6f2d776f6c743234",
   "type":"order.notification",
   "order":{
      "id":"776f6c747769646532303234",
      "venue_id":"746869736973776f6c743234",
      "status":"READY",
      "resource_url":"https://pos-integration-service.wolt.com/orders/776f6c747769646532303234"
   },
   "created_at":"2024-10-06T12:00:00.012345Z"
}

Wolt always sends the JSON body in compact format, as in the curl request. The body received from the webhook is the payload Wolt uses to generate the signature.

Order integration workflow

Diagram describing the implementation of iPad-free restaurant integration for regular delivery orders

1. New order notification is sent to partner

When Wolt receives an order from a customer we send an order created webhook notification to your webhook server.

The webhook notification will contain a HMAC signature in the header. Use it to verify that the notification came from Wolt.

Order created notification payload example

{
  "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"
}

2. Partner pulls order details from Order API (optional)

Order created webhook notification doesn't include the full order details. If you need the order details you can fetch them from the URL returned in the order created notification. Fetch order details from the URL indicated by the resource_url field. Alternatively, you could hard-code the base url and use the order ID in the webhook notification to get the right order details.

For details, refer to get order endpoint.

3. Partner accepts order automatically

The accept endpoint can be called automatically or manually by pushing a button in the POS. We recommend offering both options so that venues that don't qualify for auto-accept can benefit from this implementation

Orders can be accepted with or without an adjusted preparation time. If no adjusted preparation time is sent with the request courier will arrive as per the pickup_eta in the order payload.

We have the ability to set a fixed preparation time for a venue. If this feature is in use courier's pickup ETAs are adjusted if they are shorter than the preparation time. Wolt account managers can set this preparation time for each venue.

For details, refer to accept order endpoint.

4. Order accepted notification is sent to partner

When an order is accepted we send an order accepted webhook notification. This lets your system know that it can pull the order details from Wolt's system.

Order accepted notification payload example

{
  "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"
}

5. Partner pulls order details from Order API

Order accepted webhook notification doesn't include the full order details. To get the order details and more accurate pickup ETA you must fetch the order details from the resource_url field returned in the order created notification. You can also hardcode the base URL and use the order.id field's value to pull order details.

For details, refer to get order endpoint.

6. Courier arrival notification is sent to partner

When our courier is getting closer to your venue for pick up we send courier arrival webhook notification. This notifications lets your system know the estimated time when the courier will arrive to your venue.

Courier arrival webhook notification is sent once based on a venue's preparation time. If a venue's preparation time is 10 minutes then courier arrival webhook notification gets send 10 minutes before the courier's arrival at the venue. Courier's arrival to the venue is calculated based on the courier's GPS location. This is also known as geo-fencing.

Venue's preparation time can be configured by Wolt account manager.

Courier arrival notification example

{
  "id": "6278d17060f7596392151fe2",
  "type": "courier.notification",
  "order": {
    "id": "6278d13b14cfacea171f08fd",
    "venue_id": "624435265ea2063dfd7681ed",
    "resource_url": "https://pos-integration-service.development.dev.woltapi.com/orders/6278d13b14cfacea171f08fd"
  },
  "courier_details": {
    "courier_pickup_eta": "2022-05-09T08:33:03Z"
  },
  "created_at": "2022-05-09T08:31:44.285646Z"
}

7. Partner sends order to their own system

After receiving order details from Wolt put the order to your own system. Start the food preparation.

8. Partner marks order sent to POS (optional)

When an order is sent to your system you can mark the order sent to POS using Wolt's API. This notifies Wolt that the order is sent to your system.

Calling this endpoint ensures seamless communication between our platform and your system, enhancing visibility and troubleshooting capabilities.

For details, refer to mark order sent to POS endpoint.

9. Partner marks order ready after food preparation (optional)

When an order is ready your system you can mark the order ready using Wolt's API. This notifies Wolt that the order is ready to be picked up.

For details, refer to mark order ready endpoint.

10. Order ready notification is sent to partner

When an order is marked ready we send order ready webhook notification. This will let you know that the delivery is marked ready for pickup.

Order ready notification 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"
}

11. Courier picked up notification is sent to partner (optional)

When an order is picked up by our courier, we send pickup completed webhook notification. This will let you know that the order was picked up by the courier in the store.

Pickup completed notification 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"
}

12. Order delivered notification is sent to partner

When an order is marked delivered by our courier, we send order delivered webhook notification. This will let you know that the order was delivered.

Order delivered notification 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"
}

Pre-order integration workflow

Diagram describing the implementation of iPad-free restaurant integration for scheduled orders / pre-orders

Pre-orders or scheduled orders have a similar flow to that of regular orders, with one key difference. Pre-orders must not be accepted, they should only be confirmed from the POS. All confirmed pre-orders are automatically accepted by our system as the delivery time approaches.

For details, refer to confirm pre-order endpoint.

Takeaway order integration workflow

Takeaway orders are those that are picked up by the consumer themselves. Such orders follow the same flow as regular order, with a few key exceptions:

Takeaway orders do not receive any courier arrival notifications
Takeaway orders must be marked as ready when packed and delivered once picked up

Marking takeaway orders as ready and picked up

Use the same ready endpoint to mark takeaway orders as ready once they are prepared and packed for pickup.

For details, refer to mark order ready endpoint.

Marking takeaway orders delivered

When takeaway orders have been picked up you must mark the order delivered.

If you don't mark order delivered payment will not be collected.

For details, refer to mark order delivered endpoint.

A menu side integration allows partners to manage venue specific menus from a POS/order management system.

Externals cannot manually edit the menu using the Wolt Merchant Admin if this API is use.

Create new menus by sending the menu details in the described format. Menus pushed to Wolt are processes asynchronously and will reflect in under a minute.

Calling this endpoint erases the entire menu and creates a new one. Any specials, custom commissions, or other manual edits on the menu will be lost.

For details, refer to create menu endpoint.

Updating items

Items are products for sale on a menu. They are also called offerings on the Wolt platform. Items may experience outage or price changes over time. These changes can be pushed to a venue's menu using the items update endpoint. Discounted prices for items can also be set using this endpoint.

For details, refer to update menu items endpoint.

For details, refer to get venue status endpoint.

Set venue offline or online

Venues can be set offline using the offline endpoint. The same endpoint can be used to set a venue online by specifying it in the payload.

For details, refer to update venue online status endpoint.

Update venue opening times

A venue's opening hours can be set directly from POS or from a partner's back office system.

For details, refer to update venue opening times endpoint.