Wolt Drive

Wolt Drive API is intended for merchants who want to use Wolt as a last mile carrier partner for their deliveries.

Using Wolt Drive gives you the possibility of using your e-commerce site, inventories, payment systems, and customer service, while still leveraging the fleet of Wolt courier partners. Your customers place an order on your app or online store, and in less than one hour it’s in their hands.

Before beginning the development, get in touch with the local Wolt Drive team to receive the staging credentials. For any technical issues or questions, reach out to your Wolt contact person or your technical account manager.

The Drive order flow

The flow for requesting a delivery from Wolt Drive API contains two steps which are described below.

First request: Delivery availability check

Use /shipment-promises or /delivery-fee endpoints to see if Wolt can be used Wolt as a carrier for a delivery from point A to point B. If the response if valid, response will also include the price and an estimated delivery time.

As an additional step, /available-venuesendpoint can be used to pre-filter the available venues.

Second request: Delivery creation

Use /deliveries or /delivery-order endpoints to create the delivery. Provide all mandatory information, and add as much additional information as you have available to provide a great user experience.

Tracking the order status: Webhook service & tracking page

Use the webhook service to receive information related to the status of the created delivery. For example, follow any updates to estimated pickup times and get notified of a successfully delivered order without leaving your POS.

A tracking URL is generated for each order. An SMS can be sent directly to the customer including this URL, so the customer can follow the order ETAs and courier partner location in their web browser.

Wolt Drive orders are not visible in any other Wolt application.

Requirements

Fast deliveries might require some extra thought. Please take into consideration how these technical requirements are addressed in your specific setup, some might already be solved.

• Ability to present and maintain accurate inventory per venue.

  • Nature of ASAP deliveries is to be quick. Make sure that the items you are selling are ready at pickup time.

• Ability to decide which venue is used.

  • Merchant needs to define the pickup point. Decision can be based on factors like customer preference, delivery distance, venue busyness and item availability.

• Ability to limit deliveries to venue opening hours.

  • If Wolt is open in the area, endpoints return valid order responses. Make sure you don’t allow ASAP orders when the venue is closed, but consider allowing customers to place a scheduled order instead.

• Ability to gather all needed information for delivery.

  • The richer the information, the better. Great deliveries can only happen if everyone knows what they need to do and where to go. Present an input text field for customers to give additional instructions for delivery. Customers often want to tell the courier partner their door code or floor number.

• Ability to notify venues about the upcoming delivery order.

  • Notify the venue about the received order, make sure they are updated on its status and have enough time to prepare everything. Wolt Drive orders are not visible in other Wolt applications.

• Proper error handling and messaging.

  • Customer outside delivery area? Let them know, so they don’t keep retrying. Networking error? Retry, and later notify the customer and the venue if delivery still hasn’t been created.

Venueful and venueless

Wolt Drive API offers two different endpoint solutions for venue configurations.

Venueful

• Merchant’s venues are all pre-configured and updated in Wolt’s operational tools.
• Pre-configured information means better reporting, unified courier experience
• Recommended for merchants who have venues with large order volumes, like restaurants.
• Endpoints: shipment-promises, deliveries, available-venues

Venueless

• Merchant provides detailed venue info with every delivery request.
• Recommended for merchants with a large number of venues with small (below 5 per day) volume, like retail chains.
• Endpoints: delivery-fee, delivery-order

Merchants can also utilize both endpoints if needed. Venueless can also be utilized for very dynamic deliveries, where a specific pickup point is used only once.

Venueful endpoints

Shipment promise

The purpose of the shipment promise is to provide the merchant an easy way to ask:

• Can you deliver from this venue to this location?
• If you can, how long will it approximately take and cost?

In other words, the shipment promise provides a way to check whether the merchant can use Wolt as a carrier for a delivery from point A to point B. The request payload should contain either the address or coordinates (latitude and longitude) of the delivery recipient. The response contains information about the estimated time and price of the delivery. Additionally, the response payload contains the expiration time for the created promise. Pickup point for delivery is defined in the request path as the venue ID.

Shipment promise also allows receiving an estimate of the total delivery price, including any extra fees related to delivery capability requirements. To receive the full price estimate, include the parcel data into the request.

The response also contains a unique identifier for the created shipment promise which must be provided as part of the request payload the delivery (see Delivery). Thus, a shipment promise has to be requested before requesting a delivery. It is also highly recommended to request a shipment promise before offering the customer the option to use Wolt Drive as the delivery method.

The merchant system can request a shipment promise multiple times during a single shopping session of their customer. For example, if the customer does not finalize the order within the validity period of a shipment promise or address details are changed, a new shipment promise must be requested.

The delivery location information can be provided as an address (city, postal code, street) or as a combination of coordinates and address. If only address information is provided, we'll geocode the address and return also coordinates in the response payload. Geocoding will always return some result so the endpoint cannot be used for address format validation. If the request payload contains coordinates, an address information must also be provided. Possible combinations are explained in the API documentation.

Shipment promise can also be invalid, if the recipient is located outside the delivery area or request is outside Wolt’s operating hours. When this happens, customer should not be presented the option or allowed to confirm delivery using Wolt Drive.

Delivery

The seconds step is to request delivery. The payload of the delivery request should contain for example the following information:

• The ID of the shipment promise which was created in Shipment Promise
• Information about the delivery recipient (e.g. name and phone number)
• Information about the parcels to be delivered
• Full location of the recipient (drop-off location), which must match the information returned in the response payload of the shipment promise

Available venues

Additionally, the merchant may also request a list of available venues that have been set up in Wolt's system and are available for delivery to recipient's location. This list can be used for automatic pickup point selection or to allow the user to choose from a list of venues without needing numerous shipment promise requests.

Payload should include the dropoff location and, optionally, the scheduled dropoff time. The response includes a list of details:

• Venue IDs and localized names
• Delivery fees
• Pre-estimates for different stages of the delivery process, including minimum, mean, and maximum values for the complete delivery.

If no venue is available for delivery, the list is returned as empty. Note that filtering closed or out-of-stock venues is still on the merchant's responsibility.

Venueless endpoints

Delivery fee

Like shipment promise endpoint, the delivery fee endpoint is used to check availability of Wolt for a given time, determine estimated price and delivery time. However as a venueless endpoint, delivery fee endpoint can be used without any predetermined venue address.

API Response does not include any information that should be sent back to Wolt on venueless delivery creation. Delivery fee responses also do not include an identifier or validity time. Technically this request is optional, but operationally it is crucial to check availability and price of the delivery.

Otherwise the delivery fee endpoint responds with the same information as the shipment promise response. Merchant can also create multiple delivery fee requests when needed.

Delivery order

The deliveries endpoint is used to request a delivery when you have all required customer/order information and customer has “placed” their order. Venueless delivery endpoint requires merchant to include all relevant venue information every time a request is made. Endpoint does not require any data from other responses, but using delivery fee endpoint is recommended to use before delivery to ensure availability, delivery time and price.

Creating a delivery with venueless API will require all relevant pickup information to be added. This includes address and/or coordinates, pickup comments and contact details.

Managing live orders

Receiving information about the orders - webhooks

After a delivery is created, webhooks provide a mechanism for the merchant to receive information related to e.g. status changes of a single delivery. The Wolt Drive API contains CRUD endpoints for managing the webhooks. The webhooks operate in the merchant level: the webhook events related to all the venues of the merchant will be sent to the same endpoint. I.e. the merchant needs to configure only a single webhook in order to receive all the events related to all the stores.

The merchant system will need to provide a client_secret for each webhook it registers. Each event information is encoded into a JSON Web Token (JWT) and will be sent in the format: "token": "<payload as encoded JWT>". When the merchant system receives a payload, it can decode the payload by using the secret which it provided while registering the webhook. This way the merchant system can verify that the event is sent by the Wolt system.

The following sequence diagram visualizes the webhook related operations:

Understanding delivery ETA

Deliveries are not rejected, even if no couriers are available at the exact moment an order is placed. A courier partner is always assigned after the order has been created. If the assigned courier partner is completing another delivery, they will receive the new task once their current delivery is finished. Due to the flexibility of this assignment process, understanding the origin of each ETA is important.

When you create an availability validation request, Wolt calculates a rough estimate for both the delivery and pickup ETAs. This uses a lightweight model and is therefore relatively imprecise. Next, when you place the order, the system instantly provides another rough estimate based on similar logic to the first.

Once the delivery is created, the optimization process begins. The first optimization run completes within 30–60 seconds, at which point a true, optimized ETA is established. This estimate is highly accurate and aims to schedule the pickup as close as possible to “now” plus the “minimum_prep_time,” while optimizing the entire Wolt delivery system. After this, the optimizer runs continuously every 30–60 seconds, with the exact timing depending on the number of active optimizations in the city. Subsequent updates may slightly adjust the ETA, though these changes are typically minor. However, unexpected events, such as couriers going offline, can still cause adjustments.

How this is best implemented and taken into consideration in integrations that require extreme time accuracy, like fast food:

• Wait for the first order.pickup_eta_updated webhook event from us before treating the ETA as a true ETA. In practice, a delay of 90 seconds from placing an order ensures that by that time you will have a more accurate ETA.
• If the system prints a paper slip with time estimates, delay the print until the first update is received.
• After that, keep listening to ETA changes and forward the updates to employees, if possible.
• For kitchen systems or other picking&packing, the best solution is sending the order to the kitchen X minutes before arrival, based on the latest ETA from us + dynamic prep time from the kitchen.

Information available to the Wolt courier partner

The courier partner will see the following information while delivering the order:

• First name and the first letter of the last name of the recipient. For example, if the recipient name is John Doe, the courier partner will see John D. When an ID check is required, the complete name is revealed.
• The address of the recipient and dropoff comment.
• The coordinates of the recipient (as a "pin" on a map).
• The description and identifier of each parcel.
• The order_number. If order number is not present, merchant_order_reference_id is shown instead.

Additionally, the courier partner will be able to call the recipient, but won't be able to see the recipient's real phone number (and vice versa) as there's a proxy service in between.

If some delivery features, such as identity verification, are activated or if local policies require it, more detailed information may be shown.

Consider the above mentioned data points while designing a process which ensures that the Wolt courier partner can e.g. identify or communicate the correct parcel(s) they come to pick up. For example, if there's a receipt or label containing some unique identifier attached to the parcel(s), it would be beneficial to communicate that via the parcel identifier field in the API.

Order modifications

After an order is created, its details cannot be changed anymore via endpoints. For editing order details, the order can be cancelled and recreated using a new order identifier (merchant_order_reference_id). Note that recreating the order will start the delivery process from beginning. If cancellation is not possible, any significant error in delivery details like customer address needs to be handled in co-operation with the local Wolt support.

Cancellations

Drive API deliveries can be cancelled after creation. Cancellation feature can be used for example on customer request, or when needed items are not available for delivery.

Deadline for cancelling a delivery is when a Wolt courier partner accepts and starts the pickup task. Exact moment for delivery task start depends on the order preparation time and courier availability. Task start is optimized to happen roughly at pickup time minus courier travel time. To support timing and user experience, use webhook event order.pickup_started. Cancellation reason is required. Reason field is free-form text and it will be visible on Wolt’s system.

Sending a cancellation after pickup has started will return error 400 and no further automated action is taken. Such orders need to be canceled by contacting support.

See the endpoint documentation: Order cancellation

Payload features

Fast OR Scheduled deliveries

The API supports two separate use cases: fast deliveries (ASAP deliveries) and deliveries with scheduled drop off time. The former is for "I want this as soon as possible" while the latter is for "I want this tomorrow at 6:15pm".

Delivery time is the time it takes from the delivery request to have the parcel(s) delivered to the recipient.

Fast Delivery

Example timeline:

Fast delivery is referred to as an ASAP delivery and is intended for deliveries which target to less than 1 hour delivery time. Fast delivery is in use if the client does not specify scheduled_dropoff_time in the shipment promise request.

Scheduled dropoff

Example timeline:

Delivery with scheduled dropoff is in use if the client specifies scheduled_dropoff_time in the requests. When in use, Wolt will aim to deliver the order at exactly the requested time. As a result, a pickup time is calculated and returned based on travel time to dropoff location. To ensure the pickup time is not too early, consider still including the min_preparation_time_minutes into the request even when scheduling orders.

Pricing

Shipment promise and delivery fee endpoints return an estimated price for requested delivery. This is the price based on merchant’s contract with Wolt and confirms what Wolt will invoice from the merchant on the delivery, excluding possible additional fees. Prices include the local VAT. Providing as much details as possible in these requests might make the estimates more accurate and already include some of the additional fees.

Merchant may decide on a different price to charge from the customer. Actual customer paid delivery fee is not returned to Wolt in any request.

Prices are subject to change and should not be hard coded into payloads.

ID check

Delivery options include a possibility to request the courier partner to verify the customer's ID at delivery. Along with the enabled feature flag, a tag should be sent to further explain why the check is needed. For example, in some countries delivering alcohol is legally restricted to recipients who are over 18 years old. A merchant in that market should therefore enable the ID verification requirement, and tag the affected items as alcohol. See ìd_check_required and tagsfields in /deliveriesand /delivery-orderrequests.

Delivery handshake verification

The delivery handshake verification is a proof-of-delivery feature for confirming that parcels are received by the right person. End-customers must give the defined PIN to the courier when they receive their delivery. Verification is enabled on order-level, allowing merchant to build logic like "require only on orders above 100€".

A PIN is generated by Wolt after the delivery is created. Once a PIN is generated, it is essential for the end-customer to be informed prior to the delivery. To ensure the customer is aware of the PIN, Wolt dispatches an SMS directly to the recipient phone number. This message is distinct and separate from other notifications related to the delivery. SMS can be disabled using a feature flag, if PIN is delivered some other way.

For technical use, the PIN is available through a GET endpoint. This lets systems get the PIN automatically and inform the customer there. In addition, a webhook event is sent when a PIN is made, providing another instant update.

Customers can also find the PIN in the Wolt delivery tracking user interface, when used.

Cash

In some markets, Wolt can collect cash on delivery on merchant’s behalf. Cash feature needs to be enabled by Wolt per merchant before using.

The API payload includes two fields for cash transactions: cash.amount_to_collect and cash.amount_to_expect. For example, consider a customer with only a 50€ note to pay for a delivery. The delivery consists of items valued at 26.20€ and an 8.60€ delivery fee, totaling 34.80€. The fields should be set as follows: cash.amount_to_collect: 3480 and cash.amount_to_expect: 5000. This enables the courier partner to prepare 15.20€ in change.

Prices are always represented in whole numbers, using the smallest currency unit (typically cents).

Note that amount_to_expect is not a required field, but provides a smoother user experience for customers and courier partners.

Tipping

In some markets, it’s customary that the end-customer tips the courier partner. Any prepaid tip should be included in the dedicated payload field, so the courier partner can receive the tip as a payout through official channels. If using cash, the tipped amount should also be included in cash_to_collect value. Courier tips are invoiced from the merchant as part of the normal invoicing cycle.

SMS notifications

Wolt can send an SMS notification with tracking information directly to end-customer, when requested. SMSs can be sent immediately when the order is received, and when order has been picked up for delivery. When using venueful endpoints, merchant provides the SMS content in /deliveriespayload and can freely decide the content. On venueless endpoints, SMS contents are set as a static values in Wolt's system by Wolt contact person.

API integration

Example architecture

Each system is of course unique but here's a simplified example of what the architecture of a merchant system could look like:

While designing the merchant side architecture, keep in mind that the API key(s) are shared secret(s) between the merchant and Wolt. The API key(s) are meant for secured communication between servers and thus they should never reach end user facing client applications (e.g. the mobile app of the merchant).

Rate limiting

The endpoints of the Wolt Drive API utilize a rate limiter.

If the client system is calling the endpoint(s) with abnormal frequency, this will be indicated with the HTTP response status code 429.

Test environment

Wolt provides a staging environment which can be used while developing / testing the integration.

Ask your Wolt contact person to provide you a test venue identifier and access token for the staging environment.