Restaurant self-delivery integration

Use case

Local and global self-delivery 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.

Such self-delivery partners need an iPad-free solution from Wolt, so that they can manage all their Wolt operations from a single device or POS. This is possible with the restaurant iPad free integration plan.

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 self-delivery order
Order API	Reject order
Order API	Mark order ready
Order API	Confirm pre-order
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.

Wolt delivery vs self-delivery

Wolt delivery and self-delivery both use the same order flow and the Order API.

	Wolt delivery	Self-delivery
Who does the delivery?	Wolt courier	Partner's courier
Order webhooks	Same for both models	Same for both models
Order API endpoint	Same for both models	Same for both models
Payload differences	No consumer phone number Consumer's first name and first letter of last name	Address object Consumer phone number Consumer full name
Accept endpoint	Body needs to available as `{}` Updated preparation time can be sent back but is optional	If an updated time is sent back, it is treated as the total delivery time, i.e. the time when the order will be delivered to the consumer's doorstep
Mark orders ready	Same for both models.	Same for both models.
Mark orders delivered	Only available for takeaway orders where consumer picks up the order from the venue.	Mandatory to mark orders delivered as Wolt doesn't know when the order gets delivered. Marking orders delivered triggers payouts - if orders are not marked as delivered payout and commissioning is hampered.

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 or manually

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

For details, refer to accept self-delivery order endpoint.

Orders can also be rejected. We recommend not to automate order rejection in case auto-accept is being used.

For details, refer to reject order endpoint.

4. Order accepted notification is sent to partner

When order is marked accepted we send 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 sends order to their own system

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

6. 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.

7. Order ready notification is sent to partner

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

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.

Updating options

Options or modifiers may experience outage or price changes over time. These changes can be pushed to a venue's menu using the options update endpoint.

For details, refer to update menu options endpoint.

Venue integration workflow

Partner's Wolt venues can be managed directly from POS or a partner's back office. This integration is critical for the iPad free implementation.

Get venue status

You can pull a venue's statuses and put them onto a dashboard. This allows partners to track offline times and situations where a venue is offline and needs to be put back online. Further, the latest 3 order status can be used to gauge the "health" of a venue. If orders are getting rejected, steps to remedy the situation can be taken.

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.