Retail advanced API integration

APIs to use for this integration

This implementation requires you to use Wolt Merchant app

The Wolt merchant app lite is needed for picking products and in-store operations.

API	Endpoint
Order API	Order status webhook notification
Order API	Get order
Menu API	Get menu
Menu API	Update menu items
Menu API	Update item inventory
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

retail order with manual accept from the wolt picker app implementation

1. Order appears in the Wolt merchant app or merchant app lite

An order placed by a consumer appears on the Wolt merchant app. If the merchant app lite is being used as well, the order will appears in both devices.

2. Order is accepted on the Wolt merchant app or merchant app lite

Orders are manually accepted by the venue staff using either of the apps.

3. Order is picked using the merchant app lite [formerly picker app]

The Wolt merchant app lite must be used to pick orders that appear in the list. Missing items and substitutions are handled via the app.

4. Order is marked ready on the merchant app lite

Once the picking is completed, an order is marked ready from the app lite.

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

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

7. Partner pulls order details from Order API

Order ready webhook notification doesn't include the full order details. To get the order details 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.

Order payload will reflect the latest updates made by the merchant app lite. This means that any items marked as missing or substituted will change the order payload.

For details, refer to get order endpoint.

8. Partner sends order to their own system

After receiving the final order details from Wolt put the order to your own system.

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

Menu API is rate limited

Get menu and items update API have a rate limit of 1 call every 15 minutes and inventory update API has a rate limit of 1 call every 5 minutes. All rate limits are at the venue level.

Menu API allows integrated partners to pull menus from a Wolt venue. This allows our partners to keep track of what is being sold and mark items and options out of stock without needing to build a full fledged menu editor.

For details, refer to get 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.