Wolt Drive API

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

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.

On this page

Summary Authentication Shipment promise Shipment promise object Venueful delivery order Venueful delivery order object Available Venues Available Venues object Delivery fee Delivery fee object Venueless delivery order Venueless delivery order object Live order features Live order features object Delivery areas Delivery areas object

Authentication

Bearer authentication

Wolt Drive API uses basic authentication to authenticate your requests. Add your token into Authorization header for each request. Replace {{access_token}} in the example requests with your token. The token is also referred as "merchant key".

Test token will be provided by Wolt when you start the integration development and the production token when you successfully complete the testing phase. Only one token per merchant is needed.

You can get credentials by contacting your Wolt account manager or technical account manager.

Shipment promise

This is a venueful endpoint to request a shipment promise. See endpoint documentation for more information.

Shipment promise contains estimated delivery time and price based on destination location and other inputs. The promise can be binding or non-binding.

Promise is binding when the location is detailed enough for time estimate to be accurate.
Promise is non-binding when the location is not precise enough and time is a rough estimate.

In the case of non-binding promise it's not possible to create a delivery order using the promise. Promise creation is rather flexible but estimate accuracy depends on inputs.

There are multiple ways to create a shipment promise:

lat + lon AND ((street + city) OR (street + post_code))`: the preferred way of creating a binding promise with most accurate estimates
street + city: yields a binding promise with accurate estimates
street + post_code: yields a binding promise with accurate estimates
post_code or city only: a non-binding promise with rough estimates and it is not possible to create a delivery order with it
lat AND lon - a non-binding promise with an accurate estimate. Add street and city name for a binding promise.

Note that the endpoint cannot be used for address input validation. If the address does not exist, the endpoint will form a "best guess" of the location and resolve delivery availability using that address.

Providing parcel and cash information when relevant will enable more accurate price estimates.

Endpoints

post/v1/venues/{venue_id}/shipment-promises

The Shipment promise object

Properties

idstring

Required. Unique identifier for shipment promise. Promise ID is used for creating a delivery order.

created_atstring

Required. The date and time (ISO 8601 format) when the shipment promise was created.

valid_untilstring

Required. The date and time (ISO 8601 format) when the shipment promise will expire.

pickupobject

Required. The pickup location of the requested delivery.

dropoffobject

Required. The dropoff location of the requested delivery.

priceobject

Required. Price for the requested delivery. VAT included.

time_estimate_minutesinteger

Required. WARNING: This field is deprecated, use dropoff.eta_minutes or dropoff.options.scheduled_time in order to determine the delivery estimate.

is_bindingboolean

Required. Determines if enough information has been provided and further delivery order can be created from this promise.

parcels[object]

Parcels included in the delivery.

Shipment promise object example

{
  "id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "valid_until": "2019-08-24T14:15:22Z",
  "pickup": {
    "venue_id": "string",
    "location": {
      "coordinates": {
        "lat": 0,
        "lon": 0
      },
      "formatted_address": "string"
    },
    "options": {
      "min_preparation_time_minutes": 0
    },
    "eta_minutes": 0
  },
  "dropoff": {
    "location": {
      "coordinates": {
        "lat": 0,
        "lon": 0
      },
      "formatted_address": "string"
    },
    "options": {
      "scheduled_time": "2019-08-24T14:15:22Z"
    },
    "eta_minutes": 0
  },
  "price": {
    "amount": 0,
    "currency": "EUR"
  },
  "time_estimate_minutes": 0,
  "is_binding": true,
  "parcels": [
    {
      "dimensions": {
        "weight_gram": 0,
        "width_cm": 0,
        "height_cm": 0,
        "depth_cm": 0
      },
      "price": {
        "amount": 0,
        "currency": "AZN"
      },
      "count": 1
    }
  ]
}

Venueful delivery order

A venueful endpoint to create a delivery order. Response will include the detailed information for the delivery. See endpoint documentation for more information.

Endpoints

post/v1/venues/{venue_id}/deliveries

The Venueful delivery order object

Properties

idstring

Required. Unique identifier for the delivery order response.

statusstringenum: INFO_RECEIVED

Required. Status of the delivery order.

trackingobject

Required. Tracking information for the delivery order.

pickupobject

Required. The pickup location of the delivery order.

dropoffobject

Required. The dropoff location of the delivery order.

priceobject

Required. Price of the delivery order.

recipientobject

Required. Details of the recipient who is going to receive the parcels.

parcels[object]

Required. Parcels included in the delivery.

customer_supportobject

Required. Customer support contact information which will be shown for the customer in the Wolt tracking UI.

wolt_order_reference_idstring

Required. Unique identifier for referencing the Wolt order.

merchant_order_reference_idstring

Any kind of external reference which links back to the delivery order.

tips[object]

Required. Any additional monetary pre-delivery tips for courier partner.

order_numberstring

A short reference which links back to the delivery order.

Suggested to be 5 chars or under. If present, is shown to courier partner instead of merchant_order_reference_id.

Venueful delivery order object example

{
  "id": "string",
  "status": "INFO_RECEIVED",
  "tracking": {
    "id": "string",
    "url": "string"
  },
  "pickup": {
    "location": {
      "coordinates": {
        "lat": 0,
        "lon": 0
      },
      "formatted_address": "string"
    },
    "comment": "string",
    "options": {
      "min_preparation_time_minutes": 30
    },
    "eta": "2023-01-23T14:21:00Z",
    "display_name": "string"
  },
  "dropoff": {
    "location": {
      "coordinates": {
        "lat": 0,
        "lon": 0
      },
      "formatted_address": "string"
    },
    "comment": "string",
    "options": {
      "is_no_contact": false,
      "scheduled_time": "2023-01-23T14:21:00Z"
    },
    "eta": "2023-01-23T14:21:00Z"
  },
  "price": {
    "amount": 0,
    "currency": "EUR"
  },
  "recipient": {
    "name": "string",
    "phone_number": "string",
    "email": "string"
  },
  "parcels": [
    {
      "dimensions": {
        "weight_gram": 0,
        "width_cm": 0,
        "height_cm": 0,
        "depth_cm": 0
      },
      "description": "string",
      "identifier": "string",
      "dropoff_restrictions": {
        "age_limit": 0,
        "identity_verification": {
          "name": "string"
        }
      },
      "tags": [
        "alcohol"
      ],
      "count": 1,
      "price": {
        "amount": 0,
        "currency": "EUR"
      }
    }
  ],
  "customer_support": {
    "url": "string",
    "email": "string",
    "phone_number": "string"
  },
  "wolt_order_reference_id": "string",
  "merchant_order_reference_id": "string",
  "tips": [
    {
      "type": "pre_delivery_courier_tip",
      "price": {
        "amount": 0,
        "currency": "EUR"
      }
    }
  ],
  "order_number": "string"
}

Available Venues

This is a venueful endpoint to request a list of available venues. Requesting available venues is an additional step that can simplify the process of filtering available venues for delivery.

Endpoints

post/merchants/{merchant_id}/available-venues

The Available Venues array

Properties

pickupobject

Location of the pickup.

feeobject

Delivery fee

pre_estimateobject

Pre-estimates for delivery time

scheduled_dropoff_timestring

Scheduled dropoff time

Available Venues array example

[
  {
    "pickup": {
      "venue_id": "string",
      "name": [
        {
          "lang": "fi",
          "value": "string"
        }
      ],
      "location": {
        "formatted_address": "string",
        "coordinates": {
          "lat": 0,
          "lon": 0
        }
      }
    },
    "fee": {
      "amount": 0,
      "currency": "EUR"
    },
    "pre-estimate": {
      "pickup_minutes": 0,
      "delivery_minutes": 0,
      "total_minutes": {
        "min": 0,
        "mean": 0,
        "max": 0
      }
    },
    "scheduled_dropoff_time": "string"
  }
]

Delivery fee

This is a venueless endpoint to request a delivery fee estimate.

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

See endpoint documentation for more information.

Endpoints

post/merchants/{merchant_id}/delivery-fee

The Delivery fee object

Properties

created_atstring

Required. The date and time (ISO 8601 format) when the delivery fee was created.

pickupobject

Required. The pickup location of the delivery.

dropoffobject

Required. The dropoff location of the delivery.

feeobject

Required. Delivery fee on the requested delivery.

time_estimate_minutesinteger

Total estimated time for delivery.

scheduled_dropoff_timestring

The date and time (ISO 8601 format) when the order is scheduled to be dropped off.

Delivery fee object example

{
  "created_at": "2020-01-30T10:00:13.123Z",
  "pickup": {
    "location": {
      "formatted_address": "string",
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    }
  },
  "dropoff": {
    "location": {
      "formatted_address": "string",
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    }
  },
  "fee": {
    "amount": 0,
    "currency": "EUR"
  },
  "time_estimate_minutes": 0,
  "scheduled_dropoff_time": "2020-01-30T10:00:13.123Z"
}

Venueless delivery order

This is a venueless endpoint to request a delivery.

The delivery order 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.

See endpoint documentation for more information.

Endpoints

post/merchants/{merchant_id}/delivery-order

The Venueless delivery order object

Properties

pickupobject

Required. The pickup location of the delivery order.

dropoffobject

Required. The dropoff location of the delivery order.

scheduled_dropoff_timestring

The date and time (ISO 8601 format) when the order is scheduled to be dropped off.

customer_supportobject

Required. Customer support contact information which will be shown for the customer in the Wolt tracking UI.

is_no_contactboolean

Required. Defines if the delivery should be no-contact delivery.

merchant_order_reference_idstring

Any kind of external reference which links back to the delivery order.

contents[object]

Required. Parcels included in the delivery.

tips[object]

Required. Any additional monetary pre-delivery tips for courier partner.

priceobject

Required. Price of the delivery order.

trackingobject

Required. Tracking information for the delivery order.

wolt_order_reference_idstring

Required. Unique identifier for referencing the order.

min_preparation_time_minutesinteger

Required. Minimum preparation time in minutes that the venue needs for preparing the order.

The functionality is further explained under use cases.

order_numberstring

A short reference which links back to the delivery order.

Suggested to be 5 chars or under. If present, is shown to courier partner instead of merchant_order_reference_id.

Venueless delivery order object example

{
  "pickup": {
    "eta": "2020-01-30T10:00:13.123Z",
    "location": {
      "formatted_address": "string",
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    },
    "comment": "string",
    "contact_details": {
      "name": "string",
      "phone_number": "string",
      "send_tracking_link_sms": true
    },
    "display_name": "string"
  },
  "dropoff": {
    "eta": "2020-01-30T10:00:13.123Z",
    "location": {
      "formatted_address": "string",
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    },
    "comment": "string",
    "contact_details": {
      "name": "string",
      "phone_number": "string",
      "send_tracking_link_sms": true
    }
  },
  "scheduled_dropoff_time": "2020-01-30T10:00:13.123Z",
  "customer_support": {
    "email": "string"
  },
  "is_no_contact": true,
  "merchant_order_reference_id": "string",
  "contents": [
    {
      "count": 0,
      "description": "string",
      "identifier": "string",
      "tags": [
        "alcohol"
      ],
      "price": {
        "amount": 0,
        "currency": "EUR"
      },
      "dimensions": {
        "weight_gram": 0,
        "width_cm": 0,
        "height_cm": 0,
        "depth_cm": 0
      }
    }
  ],
  "tips": [
    {
      "type": "pre_delivery_courier_tip",
      "price": {
        "amount": 0,
        "currency": "EUR"
      }
    }
  ],
  "price": {
    "amount": 0,
    "currency": "EUR"
  },
  "tracking": {
    "id": "string",
    "url": "string"
  },
  "wolt_order_reference_id": "string",
  "min_preparation_time_minutes": 0,
  "order_number": "string"
}

Live order features

These endpoints can be used to alter the status or get details of an active delivery order.

Every live order endpoint operates on an existing order, addressed by its wolt_order_reference_id (returned when the delivery was created). Some actions are only possible before the courier partner has progressed past certain stages of the delivery.

Endpoints

patch/order/{wolt_order_reference_id}/status/cancel patch/order/{wolt_order_reference_id}/items get/order/{wolt_order_reference_id}/handshake-delivery patch/order/{wolt_order_reference_id}/courier-instructions

The Live order features object

Properties

wolt_order_reference_idstring

Unique Wolt identifier for the delivery order, used to address it in the live order endpoints.

Live order features object example

{
  "wolt_order_reference_id": "5f7e3d2a1b9c8d7e6f5a4b3c"
}

Delivery areas

Endpoint returns a polygon list of delivery areas in the merchant's operating market. These areas serve as a semi-static reference for where delivery can be offered. The intended usage is when a delivery validation cannot be done with /shipment-promises, /available-venues or /delivery-fee endpoints.

To get a realistic delivery area, user must combine the returned delivery areas with the merchant-specific maximum delivery radius to determine the final delivery coverage. This combined area can be used for customer address validation, availability checks, and any map or UI elements that show where a venue can deliver.

Usage requires a Bearer token created on or after November 2025. Reach out to your Wolt Drive contact person to receive a token with updated resources.

Endpoints

get/merchants/{merchant_id}/delivery-areas

The Delivery areas object

Properties

delivery_areasobject

Required. Map of delivery configuration names to their delivery areas. Each key is a delivery configuration name (for example Helsinki) and each value is a GeoJSON polygon describing that area. The keys are dynamic — the response contains one entry per configured delivery area.

Delivery areas object example

{
  "delivery_areas": {
    "Helsinki": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            24.105091198468067,
            60.065956192239646
          ],
          [
            24.101482004201507,
            60.081300730470225
          ],
          [
            24.139976501464847,
            60.078917944923624
          ],
          [
            24.105091198468067,
            60.065956192239646
          ]
        ]
      ]
    }
  }
}