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

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.

There are multiple ways to create a shipment promise:

  • lat AND lon AND ((street AND city) OR (street AND 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.

Additionally you can add parcel and cash information into the request for more accurate price estimates.

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

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

POST /v1/venues/{venue_id}/deliveries

Deliveries request

POST /v1/venues/{venue_id}/deliveries
{
  "pickup": {
    "options": {
      "min_preparation_time_minutes": 30
    },
    "comment": "string",
    "display_name": "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
pickupCreatePickupV1
dropoffCreateDropoffV1RequiredThe location with some additional information of the parcels destination.
pricePriceRequiredConfirmation of price for delivery. Use the price received in ShipmentPromiseDetailsV1.
recipientRecipientV1RequiredPerson who is going to receive the parcels.
parcelsParcelV1RequiredA list of parcels for a single delivery.
shipment_promise_idstringRequiredID of a binding shipment promise received from the previous step.
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. NOTE: 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

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 (venue) information.
dropoffDropoffDetailsRequiredDropoff location (end-customer) 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
{
  "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 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.
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:

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:

GET /order/{wolt_order_reference_id}/status/handshake-delivery

GET /order/{wolt_order_reference_id}/status/handshake-delivery
curl {{host}}/order/{wolt_order_reference_id}/status/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
}