Order API

Order API allows integrated partners to retrieve order details from Wolt and send them to their POS, KDS or other systems.

The API is designed to help our partners reduce the time they spend managing orders they receive through Wolt. By using all endpoints you can develop an experience that helps manage Wolt orders without the Wolt Merchant app.

For a detailed explanation of HTTP error status codes and their meanings, see the documentation.

On this page

Summary Authentication OrderV2 OrderV2 object Order Order object

Authentication

Bearer authentication

The JWT token is used for authentication and is obtained as part of the OAuth 2.0 flow. For detailed implementation guidance, refer to the documentation.

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

OrderV2

With Order V2, a more detailed breakdown of pricing of the order is provided. The pricing structure (all of it, or some of it) may be required for order creation in the POS system, taking into account the proper mapping of discounts.

Please note that any enum defined may get additional values at any point in time. Moreover, additional JSON properties may be added.

Endpoints

get/v2/orders/{orderId}

The OrderV2 object

Properties

idstring

Unique identifier for the order.

venueobject

Details of the venue where the order was placed.

basket_priceobject

Details of the basket price (ordered items and mofidiers only, excluding fees).

deliveryobject

Details about the delivery.

feesobject

Detailed fee breakdown for the order.

items[object]

Items included in the order.

created_atstringnullable

The date and time (ISO 8601 format) when the order was received by Wolt's system.

consumer_commentstringnullable

Comment added to the order by consumer.

When making an order using Wolt app, a consumer can leave a message to the restaurant. For example to inform the kitchen about dietary restrictions.

consumer_namestringnullable

Name of the consumer who made the order.

If a self-delivery venue has full name setting enabled they will receive the full name of the consumer, otherwise the name will include only first name and first letter of last name.

consumer_phone_numberstringnullable

Phone number of the consumer who made the order.

Consumer phone number is not shared unless absolutely necessary. This is toggled on only for select markets where the phone number is available on the Wolt Merchant app or for self-delivery venues. The field is null in all other cases.

pickup_etastringnullable

The date and time (ISO 8601 format) when the courier is expected to pick up the order.

attribution_idstringnullable

Unique identifier for the attribution.

This is used to track consumer "source" if the consumer is coming to Wolt from a merchant's website or app. Merchants can create a unique attribution IDs for a campaign or source and pass it to Wolt. This ID is carried through the order flow and reflected in the order.

typestringenum: preorder, instant

An order can be of two different types.

instant: When an order is to be fulfilled instantly.
preorder: When a consumer schedules an order.

pre_orderobjectnullable

Pre-order details for the order.

order_numberstring

A human readable order number that is unique only for open orders. Order numbers can repeat and are not unique for a venue.

order_statusstringenum: received, fetched, acknowledged, production, ready, delivered, rejected, other

Status of the order. An order progresses through a life cycle that consists of different states:

received: The order was fetched by the Wolt Merchant app and/or acknowledged by venue staff on the app.
fetched: The order was fetched in the Wolt Merchant app.
acknowledged: The order was interacted by venue staff on the Wolt Merchant app.
production: Preparation of the order has started.
ready: The order has been prepared and is awaiting delivery.
delivered: The order has been delivered to the consumer.
rejected: The venue or Wolt's system rejected the order.
other: Other unknown status.

modified_atstringnullable

Order modification time (UTC - ISO-8601 format)

company_tax_idstringnullable

Unique identifier for company (billing and tax purposes).

In some markets, consumers are allowed to bill their company for the purchase. In these situations they can input the company's tax ID. This information can be passed on for accounting purposes (generating an invoice). Note: This field being a non-null does not mandate company_address and company_name to be non-null.

company_namestringnullable

Name of company (billing and tax purposes).

In some markets, consumers are allowed to bill their company for the purchase. In these situations they can input the company's tax ID, with potentially also the name and the address of the company. This information can be passed on for accounting purposes (generating an invoice).

company_addressstringnullable

Address for company (billing and tax purposes).

loyalty_card_numberstringnullable

Loyalty card number given by consumer during checkout from a retail venue.

This can be only used to add points for the consumer based on the purchase. No validation of this number takes place in Wolt's system.

is_wolt_plusbooleannullable

This field indicates whether the order was a Wolt+ order or not. The presence of this field depends on the venue configuration

is_no_contact_deliverybooleannullable

For self delivery orders, this field being "true" indicates that the user has asked for the drop off to be to their "doorstep" without an interaction with the courier delivering.

cash_paymentobjectnullable

Contains information about cash payment of the order.

With this information the courier will be able to request correct amount of cash from the customer and also reserve enough change in case customer does not have even amount in cash.

group_participants[object]nullable

List of participants for a group order.

order_handlingobject

With this information you are able to trigger specific flows on your middleware for order handling - acceptance, delay for preparation and forecasted preparation time.

in_store_operationsobjectnullable

Contains information about in-store operations required as a part of handling this order.

This will be used in cases where venue staff need to perform certain additional tasks as a part of processing a purchase.

OrderV2 object example

{
  "id": "68656c6c6f6f726465727632",
  "venue": {
    "id": "68656c6c6f76326f72646572",
    "name": "Wolt's Cafe",
    "external_venue_id": "wolt_external_store"
  },
  "basket_price": {
    "total": {
      "amount": 4927,
      "currency": "EUR"
    },
    "price_breakdown": {
      "total_before_discounts": {
        "amount": 5925,
        "currency": "EUR"
      },
      "total_discounts": {
        "amount": 998,
        "currency": "EUR"
      },
      "subtotal_basket_discounts": {
        "amount": 548,
        "currency": "EUR"
      },
      "subtotal_item_discounts": {
        "amount": 450,
        "currency": "EUR"
      }
    }
  },
  "delivery": {
    "status": "none",
    "type": "homedelivery",
    "time": "2024-01-01T12:00:00.000Z",
    "location": {
      "street_address": "Pohjoinen Rautatiekatu 21",
      "apartment": "",
      "city": "Helsinki",
      "country": "FIN",
      "coordinates": {
        "lon": 60.1700444,
        "lat": 24.9254858
      },
      "formatted_address": "Pohjoinen Rautatiekatu 21\n00100 Helsinki\nFIN\n\nEntrance / Staircase: 1\nName / Number on the door: 1"
    },
    "self_delivery": false
  },
  "fees": {
    "total": {
      "amount": 145,
      "currency": "EUR"
    },
    "price_breakdown": {
      "total_before_discounts": {
        "amount": 295,
        "currency": "EUR"
      },
      "total_discounts": {
        "amount": 150,
        "currency": "EUR"
      },
      "liability": {
        "amount": 0,
        "currency": "EUR"
      }
    },
    "parts": [
      {
        "type": "type_base_delivery",
        "total": {
          "amount": 60,
          "currency": "EUR"
        },
        "vat_percentage": 12
      },
      {
        "type": "type_base_delivery",
        "total": {
          "amount": 40,
          "currency": "EUR"
        },
        "vat_percentage": 19
      },
      {
        "type": "type_delivery_distance_extra",
        "total": {
          "amount": 27,
          "currency": "EUR"
        },
        "vat_percentage": 12
      },
      {
        "type": "type_delivery_distance_extra",
        "total": {
          "amount": 18,
          "currency": "EUR"
        },
        "vat_percentage": 19
      }
    ]
  },
  "items": [
    {
      "item_type": "order-item-with-price-breakdown",
      "id": "68656c6c6f6f727632646572",
      "count": 2,
      "pos_id": "SUPERHAMBURG",
      "sku": "combo",
      "gtin": null,
      "options": [
        {
          "id": "68656c6c6f6f727632646573",
          "name": "Toppings",
          "value": "Lettuce",
          "price": {
            "amount": 0,
            "currency": "EUR"
          },
          "vat_percentage": 0,
          "price_breakdown": {
            "price_before_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "total_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_basket_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_item_discounts": {
              "amount": 0,
              "currency": "EUR"
            }
          },
          "pos_id": "toppings_added",
          "count": 1,
          "value_pos_id": "LETTUCE",
          "deposit": null
        },
        {
          "id": "68656c6c6f6f727632646574",
          "name": "Toppings",
          "value": "Tomato",
          "price": {
            "amount": 0,
            "currency": "EUR"
          },
          "vat_percentage": 0,
          "price_breakdown": {
            "price_before_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "total_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_basket_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_item_discounts": {
              "amount": 0,
              "currency": "EUR"
            }
          },
          "pos_id": "toppings_added",
          "count": 1,
          "value_pos_id": "TOMATOSLICES",
          "deposit": null
        },
        {
          "id": "68656c6c6f6f727632646575",
          "name": "Toppings",
          "value": "Truffles",
          "price": {
            "amount": 500,
            "currency": "EUR"
          },
          "vat_percentage": 0,
          "price_breakdown": {
            "price_before_discounts": {
              "amount": 1000,
              "currency": "EUR"
            },
            "total_discounts": {
              "amount": 102,
              "currency": "EUR"
            },
            "subtotal_basket_discounts": {
              "amount": 102,
              "currency": "EUR"
            },
            "subtotal_item_discounts": {
              "amount": 0,
              "currency": "EUR"
            }
          },
          "pos_id": "toppings_added",
          "count": 1,
          "value_pos_id": "TRUF",
          "deposit": null
        },
        {
          "id": "68656c6c6f6f727632646576",
          "name": "Changes",
          "value": "Gluten-free bun",
          "price": {
            "amount": 0,
            "currency": "EUR"
          },
          "vat_percentage": 0,
          "price_breakdown": {
            "price_before_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "total_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_basket_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_item_discounts": {
              "amount": 0,
              "currency": "EUR"
            }
          },
          "pos_id": "changes_burger",
          "count": 1,
          "value_pos_id": "GLT_FREE_BUN",
          "deposit": null
        },
        {
          "id": "68656c6c6f6f727632646577",
          "name": "Changes",
          "value": "No Pickles",
          "price": {
            "amount": 0,
            "currency": "EUR"
          },
          "vat_percentage": 0,
          "price_breakdown": {
            "price_before_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "total_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_basket_discounts": {
              "amount": 0,
              "currency": "EUR"
            },
            "subtotal_item_discounts": {
              "amount": 0,
              "currency": "EUR"
            }
          },
          "pos_id": "changes_burger",
          "count": 1,
          "value_pos_id": "REMOVE_PICKLES",
          "deposit": null
        }
      ],
      "item_price": {
        "unit_price": {
          "amount": 2154,
          "currency": "EUR"
        },
        "base_price": {
          "amount": 2290,
          "currency": "EUR"
        },
        "vat_percentage": 0,
        "total": {
          "amount": 4308,
          "currency": "EUR"
        },
        "price_breakdown": {
          "total_before_discounts": {
            "amount": 4800,
            "currency": "EUR"
          },
          "total_discounts": {
            "amount": 492,
            "currency": "EUR"
          },
          "subtotal_basket_discounts": {
            "amount": 390,
            "currency": "EUR"
          },
          "subtotal_item_discounts": {
            "amount": 0,
            "currency": "EUR"
          },
          "base_price_before_discounts": {
            "amount": 1900,
            "currency": "EUR"
          },
          "unit_price_before_discounts": {
            "amount": 2400,
            "currency": "EUR"
          },
          "subtotal_options_basket_discounts": {
            "amount": 102,
            "currency": "EUR"
          },
          "subtotal_options_item_discounts": {
            "amount": 0,
            "currency": "EUR"
          }
        }
      },
      "name": "Super Hamburger test",
      "category": {
        "id": "65043e12d6d9cb60a18b89ac",
        "name": "Burgers"
      },
      "deposit": null,
      "is_bundle_offer": false
    },
    {
      "item_type": "order-item-with-price-breakdown",
      "id": "68656c6c6f6f727632646562",
      "count": 5,
      "pos_id": "123",
      "sku": "123",
      "gtin": null,
      "options": [],
      "item_price": {
        "unit_price": {
          "amount": 123,
          "currency": "EUR"
        },
        "base_price": {
          "amount": 706,
          "currency": "EUR"
        },
        "vat_percentage": 7,
        "total": {
          "amount": 619,
          "currency": "EUR"
        },
        "price_breakdown": {
          "total_before_discounts": {
            "amount": 1125,
            "currency": "EUR"
          },
          "total_discounts": {
            "amount": 506,
            "currency": "EUR"
          },
          "subtotal_basket_discounts": {
            "amount": 56,
            "currency": "EUR"
          },
          "subtotal_item_discounts": {
            "amount": 450,
            "currency": "EUR"
          },
          "base_price_before_discounts": {
            "amount": 200,
            "currency": "EUR"
          },
          "unit_price_before_discounts": {
            "amount": 225,
            "currency": "EUR"
          },
          "subtotal_options_basket_discounts": {
            "amount": 0,
            "currency": "EUR"
          },
          "subtotal_options_item_discounts": {
            "amount": 0,
            "currency": "EUR"
          }
        }
      },
      "name": "coca cola test",
      "category": {
        "id": "68656c6c6f6f727632646563",
        "name": "Drinks"
      },
      "deposit": {
        "gross_price": {
          "amount": 25,
          "currency": "EUR"
        },
        "net_price": {
          "amount": 22,
          "currency": "EUR"
        },
        "vat_percentage": 16
      },
      "is_bundle_offer": false
    }
  ],
  "created_at": "2024-01-01T12:00:00.000Z",
  "consumer_comment": null,
  "consumer_name": "Yuho",
  "consumer_phone_number": "+3581234567",
  "pickup_eta": "2024-01-01T12:00:10Z",
  "attribution_id": null,
  "type": "instant",
  "pre_order": null,
  "order_number": "10",
  "order_status": "delivered",
  "modified_at": "2024-01-01T12:00:20.000Z",
  "company_tax_id": null,
  "loyalty_card_number": null,
  "cash_payment": null,
  "order_handling": {
    "preparation_time": {
      "preparation_time_seconds": 900,
      "preparation_time_source": "forecasted_by_wolt"
    },
    "acceptance_status": "auto_accepted_by_wolt",
    "courier_arrival": "notification_sent"
  },
  "in_store_operations": {
    "total_balance_to_pay_in_venue": {
      "amount": 145,
      "currency": "EUR"
    }
  }
}

Order

Order object describes an order on Wolt.

Endpoints

The Order object

Properties

idstring

Unique identifier for the order.

venueobject

Details of the venue where the order was placed.

priceobject

Total price of the order.

deliveryobject

The delivery method of the order.

items[object]

Items included in the order.

created_atstring

The date and time (ISO 8601 format) when the order was received by Wolt's system.

consumer_commentstringnullable

Comment added to the order by consumer.

When making an order using Wolt app, a consumer can leave a message to the restaurant. For example to inform the kitchen about dietary restrictions.

pickup_etastring

The date and time (ISO 8601 format) when the courier is expected to pick up the order.

attribution_idstring

Unique identifier for the attribution.

typestringenum: preorder, instant

An order can be of two different types.

instant: When an order is to be fulfilled instantly.
preorder: When a consumer schedules an order.

pre_orderobjectnullable

Pre-order details for the order.

consumer_namestring

Name of the consumer who made the order.

If a self-delivery venue has full name setting enabled they will receive the full name of the consumer, otherwise the name will include only first name and first letter of last name.

consumer_phone_numberstringnullable

Phone number of the consumer who made the order.

order_numberstring

A human readable order number that is unique only for open orders. Order numbers can repeat and are not unique for a venue.

order_statusstringenum: received, fetched, acknowledged, production, ready, delivered, rejected, other

Status of the order. An order progresses through a life cycle that consists of different states:

received: The order was fetched by the Wolt Merchant app and/or acknowledged by venue staff on the app.
fetched: The order was fetched in the Wolt Merchant app.
acknowledged: The order was interacted by venue staff on the Wolt Merchant app.
production: Preparation of the order has started.
ready: The order has been prepared and is awaiting delivery.
delivered: The order has been delivered to the consumer.
rejected: The venue or Wolt's system rejected the order.
refunded: Wolt has processed a refund for the order.
other: Other unknown status.

modified_atstring

The date and time (ISO 8601 format) when the order was last modified.

Orders move through a life cycle and can change the order status. This change is also considered a modification, so the date and time could be the time when a purchase changed its status from acknowledged to production.

company_tax_idstringnullable

Unique identifier for company tax.

In some markets, consumers are allowed to bill their company for the purchase. In these situations they input the company's tax ID and this information is passed on for accounting purposes.

loyalty_card_numberstringnullable

Loyalty card number given by consumer during checkout from a retail venue.

This can be only used to add points for the consumer based on the purchase. No validation of this number takes place in Wolt's system.

is_wolt_plusbooleannullable

This field indicates whether the order was a Wolt+ order or not. The presence of this field depends on the venue configuration.

is_no_contact_deliverybooleannullable

For self delivery orders, this field being "true" indicates that the user has asked for the drop off to be to their "doorstep" without an interaction with the courier delivering.

cash_paymentobject

Contains information about cash payment of the order.

With this information the courier will be able to request correct amount of cash from the customer and also reserve enough change in case customer does not have even amount in cash.

order_handlingobject

With this information you are able to trigger specific flows on your middleware for order handling - acceptance, delay for preparation and forecasted preparation time.

in_store_operationsobjectnullable

Contains information about in-store operations required as a part of handling this order.

This will be used in cases where venue staff need to perform certain additional tasks as a part of processing a purchase.

Order object example

{
  "id": "62db996d7706bd423bb10db6",
  "venue": {
    "id": "602fb85a64983ea30328f131",
    "name": "Burger Venue",
    "external_venue_id": "5"
  },
  "price": {
    "amount": 24200,
    "currency": "EUR"
  },
  "delivery": {
    "status": "delivered",
    "type": "homedelivery",
    "time": "2021-06-14T12:07:19.812Z",
    "fee": {
      "amount": 1000,
      "currency": "EUR"
    },
    "location": {
      "street_address": "Mannerheimintie 1",
      "apartment": "C 2",
      "city": "Helsinki",
      "country": "Finland",
      "coordinates": {
        "lon": 53.390234,
        "lat": -7.782839
      },
      "formatted_address": "Mannerheimintie 1 C 2, 00100, Helsinki\nDrive past the big rock to see the entrance.\nLeave parcel to entrance.\nDoor code: 1234\n"
    },
    "small_order_surcharge": {
      "amount": 10,
      "currency": "EUR"
    },
    "self_delivery": false
  },
  "items": [
    {
      "id": "602fb890e765db64dc152203",
      "item_type": "order-item",
      "count": 1,
      "pos_id": "1623629",
      "sku": "4232134",
      "gtin": "00369545276326",
      "options": [
        {
          "id": "602fb890e765db64dc152196",
          "name": "In the burger",
          "value": "Cheese",
          "price": {
            "amount": 1000,
            "currency": "EUR"
          },
          "pos_id": null,
          "count": 1,
          "value_pos_id": "1623576"
        },
        {
          "id": "602fb890e765db64dc1521ca",
          "name": "Side",
          "value": "Fries",
          "price": {
            "amount": 0,
            "currency": "EUR"
          },
          "pos_id": "1623560",
          "count": 1,
          "value_pos_id": "1623560"
        },
        {
          "id": "602fb890e765db64dc15219e",
          "name": "Dips",
          "value": "Bearnaise",
          "price": {
            "amount": 200,
            "currency": "EUR"
          },
          "pos_id": null,
          "count": 1,
          "value_pos_id": "1623555"
        },
        {
          "id": "602fb890e765db64dc15219c",
          "name": "Dips",
          "value": "Chipotle Mayo",
          "price": {
            "amount": 0,
            "currency": "EUR"
          },
          "pos_id": null,
          "count": 1,
          "value_pos_id": "1623553"
        },
        {
          "id": "602fb890e765db64dc1521af",
          "name": "Extras sides",
          "value": "Real Nuggets (4 stk)",
          "price": {
            "amount": 5000,
            "currency": "EUR"
          },
          "pos_id": null,
          "count": 1,
          "value_pos_id": "1623634"
        },
        {
          "id": "602fb890e765db64dc1521b0",
          "name": "Extras sides",
          "value": "Spicy Hotdog",
          "price": {
            "amount": 4000,
            "currency": "EUR"
          },
          "pos_id": null,
          "count": 1,
          "value_pos_id": "1623635",
          "deposit": {
            "gross_price": {
              "amount": 40,
              "currency": "EUR"
            },
            "net_price": {
              "amount": 30,
              "currency": "EUR"
            },
            "vat_percentage": 15
          }
        },
        {
          "id": "602fb890e765db64dc1521a9",
          "name": "Sodas",
          "value": "Lemon Soda 0,33 l",
          "price": {
            "amount": 0,
            "currency": "EUR"
          },
          "pos_id": null,
          "count": 1,
          "value_pos_id": "1623532"
        }
      ],
      "total_price": {
        "amount": 24200,
        "currency": "EUR"
      },
      "base_price": {
        "amount": 14000,
        "currency": "EUR"
      },
      "unit_price": {
        "amount": 24200,
        "currency": "EUR"
      },
      "name": "Fried Chicken Burger Combo",
      "category": {
        "id": "5bf00d226feade000a37266e",
        "name": "Combos"
      },
      "deposit": {
        "gross_price": {
          "amount": 2400,
          "currency": "EUR"
        },
        "net_price": {
          "amount": 2200,
          "currency": "EUR"
        },
        "vat_percentage": 15
      },
      "is_bundle_offer": false
    }
  ],
  "created_at": "2021-05-05T10:19:38.856Z",
  "consumer_comment": "Don't forget the ketchup please!",
  "pickup_eta": "2021-05-05T10:25:09.636Z",
  "attribution_id": "123456789",
  "type": "instant",
  "pre_order": {
    "preorder_time": "2021-05-05T10:22:16.631Z",
    "pre_order_status": "confirmed"
  },
  "consumer_name": "Frank L",
  "consumer_phone_number": "+35850111222333",
  "order_number": "485",
  "order_status": "delivered",
  "modified_at": "2021-05-05T10:22:16.631Z",
  "company_tax_id": "TXN 123 999",
  "loyalty_card_number": "loyalty-card-number",
  "cash_payment": {
    "cash_amount": {
      "amount": 200,
      "currency": "EUR"
    },
    "cash_to_expect": {
      "amount": 300,
      "currency": "EUR"
    }
  },
  "order_handling": {
    "preparation_time": {
      "preparation_time_seconds": 900,
      "preparation_time_source": "forecasted_by_wolt"
    },
    "acceptance_status": "auto_accepted_by_wolt",
    "courier_arrival": "notification_sent"
  },
  "in_store_operations": null
}