Restaurant advanced integration

Use case

Multi-venue restaurant partners experience a lot of varying order volumes while managing the same menu across their stores. Staff spend a lot of time entering orders into a POS. Orders may also contain out of stock items that lead to support hassles.

By using the restaurant advanced implementation, venue staff don't have to manually add orders to POS. Staff accept and mark orders ready in the Wolt Merchant app. The integration will handle fetching order details from Wolt into partner's system. This improves operational efficiency, lowers error rate and boosts sales.

Venue staff can also set their Wolt menus and mark out of stock items from their POS. This eliminates duplication of work when it comes to disabling or adding items. Removing duplication also reduces rejections and support bottlenecks.

APIs to use for this integration

This implementation requires you to use Wolt Merchant app

To integrate without needing to use Wolt Merchant app use iPad-free integration.

API	Endpoint
Order API	Order status webhook notification
Order API	Get order
Order API	Mark order sent to POS
Menu API	Create menu
Menu API	Update menu items
Menu API	Update menu options

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 advanced restaurant integration

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's venue accepts order in Wolt Merchant app

Your venue uses their Wolt Merchant app to accept the order they received. This marks the order accepted in Wolt's system.

3. 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"
}

4. Partner pulls order details from Order API

Order accepted webhook notification doesn't include the full order details. Your system 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.

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

7. Partner marks order ready in Wolt Merchant app

After your venue has marked an order as ready our courier will come pick it up.

8. 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"
}

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.

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.