Wolt Drive API endpoints

Note that we release new features constantly and may add optional fields in our API without creating a new API version. In practice, this could mean that some new fields are also introduced in the responses. The client side should allow unknown keys.

Base URLs

  • Staging: https://daas-public-api.development.dev.woltapi.com

  • Production: https://daas-public-api.wolt.com

Authentication

All requests to Drive API endpoints must be authorized with a Bearer Token.

All the requests must contain Authorization: Bearer <token> header. This token is often referred as Merchant Key. Staging 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.

Venueful endpoints

Shipment Promises

A venueful endpoint

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

Promise contains estimated price and delivery time based on destination location. It can be binding in case when the location is detailed enough for time estimate to be accurate. Also it can be non-binding which means that location is not precise enough and time is a rough estimate. In case of non-binding promise it is not possible to create a delivery order using the promise. Promise creation is rather flexible but estimate accuracy depends on inputs.

Requirement for min_preparation_time_minutes and scheduled_dropoff_time depend on the use case. When the delivery is to be done within next hour, scheduled_dropoff_time must not be included in the payload. Read the use case documentation for more information.

There are multiple ways to create a shipment promise:

Binding promises with accurate estimates

  • lat + lon + street + post_code + city

  • street + post_code + city

Binding promises with accurate estimates, but with a risk of address mixups (e.g., when local geolocation data is suboptimal or similar street addresses exist nearby).

  • street + city

  • street + post_code

Non-binding promises, usable when filtering venues but not for a delivery

  • post_code OR city only - a rough non-binding promise based on the general area.

  • lat + lon - a non-binding promise with an accurate estimate. Add street and city/post_code before delivery.

Formatting notes:

  • The `street` field must include the house number.

  • In addition to house number, entrance number/letter and apartment number also can be included. Depending on the complexity of local address formats, these can also be added as dropoff comments.

  • Other details (e.g., floor number, delivery instructions) should not be included in `street` but be added separately as a dropoff comment when making a delivery request.

Additionally you can add parcel and cash information into the request for more accurate price estimates, which include applicable fees. See tab "request with applicable fees" for more details.

Shipment promise request

This request validates the delivery availability based on recipient location. This price is does not include possible extra fees, based on dimensions and/or cash usage. See the second tab for requesting a final estimate based on all available details.

POST /v1/venues/{venue_id}/shipment-promises
{
  "street": "string",
  "city": "string",
  "post_code": "string",
  "lat": 0,
  "lon": 0,
  "language": "string",
  "min_preparation_time_minutes": 30,
  "scheduled_dropoff_time": "2019-08-24T14:15:22Z"
}

Shipment promise parameters

NameLocationTypeRequired
venue_idIn: pathstringRequired

ParameterTypeRequiredDescription
streetstringStreet name and house number.
citystringThe name of the city.
post_codestringPost code
latnumber"lat" and "lon" are always preferred over address details.
lonnumber"lat" and "lon" are always preferred over address details.
languagestringResponse address will be localized with this language if locale is available.
min_preparation_time_minutesintegerDefault: 30Max 60 mins. Time that the venue needs for preparing the order. Functionality is explained under payload features.
scheduled_dropoff_timestring(date-time)Target time for the scheduled pre-order dropoff. Timestamp is in ISO8601 format e.g. 2020-01-30T10:00:13.123Z. Functionality is explained under payload features.

Deliveries

A venueful endpoint to create a delivery order.

POST /v1/venues/{venue_id}/deliveries

The payload of the delivery request should contain for example the following information:

  • The ID of the shipment promise which was created in previous step

  • 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

  • Any special delivery requirements, and any information beneficial for the specific use case.

Response will include the detailed information for the delivery, including a tracking ID and URL.

Deliveries request

POST /v1/venues/{venue_id}/deliveries
{
  "pickup": {
    "options": {
      "min_preparation_time_minutes": 30
    },
    "comment": "string"
  },
  "dropoff": {
    "location": {
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    },
    "comment": "string",
    "options": {
      "is_no_contact": false,
      "scheduled_time": "2019-08-24T14:15:22Z"
    }
  },
  "price": {
    "amount": 0,
    "currency": "string"
  },
  "recipient": {
    "name": "string",
    "phone_number": "string",
    "email": "string"
  },
  "parcels": [
    {
      "count": 1,
      "dimensions": {
        "weight_gram": 0,
        "width_cm": 0,
        "height_cm": 0,
        "depth_cm": 0
      },
      "price": {
        "amount": 0,
        "currency": "string"
      },
      "description": "string",
      "identifier": "string",
      "dropoff_restrictions": {
        "id_check_required": false
      },
      "tags": [
        "alcohol"
      ]
    }
  ],
  "shipment_promise_id": "string",
  "customer_support": {
    "url": "string",
    "email": "string",
    "phone_number": "string"
  },
  "merchant_order_reference_id": "string",
  "sms_notifications": {
    "received": "string",
    "picked_up": "string"
  },
  "tips": [
    {
      "type": "pre_delivery_courier_tip",
      "price": {
        "amount": 0,
        "currency": "string"
      }
    }
  ],
  "order_number": "string",
  "cash": {
    "amount_to_collect": 0,
    "amount_to_expect": 0
  },
  "handshake_delivery": {
    "is_required": false,
    "should_send_sms_to_dropoff_contact": true
  }
}
Delivery request parameters
NameLocationTypeRequired
venue_idIn: pathstringRequired
ParameterTypeRequiredDescription
pickupCreatePickupV1Additional pickup information.
dropoffCreateDropoffV1RequiredThe location with some additional information of the parcels destination.
pricePriceRequiredConfirmation of price for delivery. Use the price received in Shipment promise response.
recipientRecipientV1RequiredPerson who is going to receive the parcels.
parcelsParcelV1RequiredA list of parcels for a single delivery.
shipment_promise_idstringRequiredUnique identifier of a binding shipment promise received in create a shipment promise response.
customer_supportCustomerSupportRequiredCustomer support contact information which will be shown for the customer in the Wolt tracking UI.
merchant_order_reference_idstringAny kind of external reference which links back to the delivery order.
sms_notificationsSmsNotificationsContent for the SMS message(s) which will be sent to the recipient at certain stage(s) of the delivery. This is an optional feature for communicating the tracking link to the recipient.
tipsTipAny additional monetary pre-delivery tips for courier partner.
order_numberstringA 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.
cashCashSupported in some regions. Check with your Wolt Drive contact if cash is included in your contract. Including this payload will enable cash on delivery, and will result in error if cash is not enabled on your account.
handshake_deliveryHandshakeDeliverySupported in some regions. Enables PIN verification on delivery. Check with your Wolt Drive contact if HSD is available. See feature documentation.

Available venues

A venueful endpoint. Additional step.

Requesting available venues is an additional step that can simplify the process of filtering available venues for delivery. When providing the dropoff location as the request, endpoint returns a sorted list of available venue names, their IDs, delivery prices and estimated delivery times.

Available venues request

POST /merchants/{merchant_id}/available-venues
{
  "dropoff": {
    "location": {
      "formatted_address": "string",
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    }
  },
  "scheduled_dropoff_time": "string"
}

Available venues parameters

NameLocationTypeRequired
merchant_idIn: pathstringRequired
ParameterTypeRequiredDescription
dropoffDropoffDetailsRequiredDropoff location information.
scheduled_dropoff_timestring(date-time)Target time for the scheduled pre-order dropoff. Timestamp is in ISO8601 format e.g. 2020-01-30T10:00:13.123Z. Functionality is explained under payload features.

Venueless endpoints

Please consult with your Wolt contact person before choosing venueless approach.

Delivery Fee

A venueless endpoint

POST /merchants/{merchant_id}/delivery-fee

Delivery fee request

POST /merchants/{merchant_id}/delivery-fee
{
  "pickup": {
    "location": {
      "formatted_address": "string",
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    }
  },
  "dropoff": {
    "location": {
      "formatted_address": "string",
      "coordinates": {
        "lat": 0,
        "lon": 0
      }
    }
  },
  "scheduled_dropoff_time": "2019-08-24T14:15:22Z",
  "contents": [
    {
      "count": 1,
      "dimensions": {
        "weight_gram": 0,
        "width_cm": 0,
        "height_cm": 0,
        "depth_cm": 0
      },
      "price": {
        "amount": 0,
        "currency": "string"
      }
    }
  ],
  "cash": {
    "amount_to_collect": 0,
    "amount_to_expect": 0
  }
}

Delivery fee request parameters

NameLocationTypeRequired
merchant_idIn: pathstringRequired
ParameterTypeRequiredDescription
pickupPickupDetailsRequiredPickup location (sender) information.
dropoffDropoffDetailsRequiredDropoff location (receiver) information.
scheduled_dropoff_timestring(date-time)Target time for the scheduled pre-order dropoff. Timestamp is in ISO8601 format e.g. 2020-01-30T10:00:13.123Z. Functionality is explained under payload features.
contents[Contents]A list of parcels for a single delivery. Providing this allows for more accurate price estimates.
cashCashSupported in some regions. Check with your Wolt Drive contact if cash is included in your contract. Providing this allows for more accurate price estimates.

Delivery Order

A venueless endpoint

POST /merchants/{merchant_id}/delivery-order

Delivery order request

POST /merchants/{merchant_id}/delivery-order
curl -X POST {{host}}/merchants/{merchant_id}/delivery-order \
  -H "Authorization: Bearer (token)" \
  -H "Content-Type: application/json" \
  -d '{"pickup":{"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":{"location":{"formatted_address":"string","coordinates":{"lat":0,"lon":0}},"contact_details":{"name":"string","phone_number":"string","send_tracking_link_sms":true},"comment":"string"},"customer_support":{"email":"string","phone_number":"string","url":"string"},"merchant_order_reference_id":"string","is_no_contact":true,"contents":[{"count":0,"description":"string","identifier":"string","id_check_required":false,"tags":["alcohol"],"price":{"amount":0,"currency":"string"},"dimensions":{"weight_gram":0,"width_cm":0,"height_cm":0,"depth_cm":0}}],"tips":[{"type":"pre_delivery_courier_tip","price":{"amount":0,"currency":"string"}}],"min_preparation_time_minutes":0,"scheduled_dropoff_time":"2019-08-24T14:15:22Z","order_number":"string","cash":{"amount_to_collect":0,"amount_to_expect":0},"handshake_delivery":{"is_required":false,"should_send_sms_to_dropoff_contact":true}}'

Delivery order request parameters

NameLocationTypeRequired
merchant_idIn: pathstringRequired
ParameterTypeRequiredDescription
pickupCreatePickupDetailsRequiredPickup location (venue) information.
dropoffCreateDropoffDetailsRequiredPickup location (end-customer) information.
customer_supportCustomerSupportRequiredCustomer support contact information which will be shown for the customer in the Wolt tracking UI.
merchant_order_reference_idstringAny kind of reference-id which links back to the delivery order.
is_no_contactbooleanRequiredBoolean for no-contact delivery. Define if the order should be left at customer's door.
contents[Contents]RequiredA list of parcels for a single delivery.
tips[Tip]RequiredAny additional monetary pre-delivery tips for courier partner.
min_preparation_time_minutesintegerRequiredMax 60 mins. Time that the venue needs at minimum to prepare the order. Functionality is explained under payload features.
scheduled_dropoff_timestring(date-time)Target time for the scheduled pre-order dropoff. Timestamp is in ISO8601 format e.g. 2020-01-30T10:00:13.123Z. Functionality is explained under payload features.
order_numberstringA 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.
cashCashSupported in some markets. Check with your Wolt Drive contact if cash is included in your contract. Including this payload will enable cash on delivery, and will result in error if cash is not enabled on your account.
handshake_deliveryHandshakeDeliverySupported in some regions. Enables PIN verification on delivery. Check with your Wolt Drive contact if HSD is available. See feature documentation.

Live order features

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

Order cancellation

Any Drive API delivery can be cancelled before a Wolt courier partner has accepted the delivery task. Exact time depends on 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. 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.

Cancellation reason is required. Reason can be any string and it will be visible on Wolt’s system.

PATCH /order/{wolt_order_reference_id}/status/cancel

Order cancellation request

PATCH /order/{wolt_order_reference_id}/status/cancel
{
  "reason": "string"
}
NameLocationTypeRequiredDescription
wolt_order_reference_idIn: pathstringRequiredReference ID as returned in delivery creation response
ParameterTypeRequiredDescription
reasonstringRequiredA free-form informative reason for the cancellation.

Order cancellation responses

Successful response, "rejected" refers to the new state of the order:

Response example
200 OK
{
    "status": "REJECTED"
}

Failed response, cancellation no longer possible.

Response example
400 Invalid payload
{
    "error_code": "INVALID_ORDER_STATE_TRANSITION",
    "reason": "Invalid order state transition",
    "details": "Order is not in a cancellable state. Please contact support to cancel it"
}

Generic error responses apply to possible order cancellation responses.

Get delivery handshake details

If a delivery has the handshake PIN verification enabled, the generated PIN and other relevant information can be fetched using a GET endpoint. Customer is required to provide the PIN for Wolt courier partner. See documentation: Delivery handshake verification

GET /order/{wolt_order_reference_id}/handshake-delivery

GET /order/{wolt_order_reference_id}/handshake-delivery
curl {{host}}/order/{wolt_order_reference_id}/handshake-delivery \
  -H "Authorization: Bearer (token)"
NameLocationTypeRequiredDescription
wolt_order_reference_idIn: pathstringRequiredReference ID as returned in delivery creation response

Expected response when handshake is enabled:

Response example
200 OK
{
    "is_required": true,
    "pin_code": 123
}