Changelog

Aug 31, 2026

Large Assortment: external_id removed from the Listing schema

Documentation update.

The unused external_id field has been removed from the Listing schema. Use product_external_id or product_catalog_lookup to link a listing to a product in the catalog; sku remains available as the store-level identifier. The SFTP hosts for the test and production environments are now documented directly in the schema page.

Aug 26, 2026

Large Assortment: 45 nutrition fields added to the product catalog

NutritionValues grew from 31 to 76 fields, closing the gap between the schema and the nutrition data partners can actually submit. The additions cover fatty acids (omega-3, alpha-linolenic, linoleic, palmitic, trans fats, DHA, EPA, arachidonic), amino acids and proteins (essential and branched-chain amino acids, casein, whey protein, taurine, carnitine, nucleotide), vitamins (B1, B2, B6, E, niacin, pantothenic acid, biotin, choline, inositol), minerals (iron, zinc, copper, manganese, phosphorus, bicarbonate, sulfate, salt equivalent, nitrates), and sugars and other compounds (glucose, sucrose, lactose, maltodextrin, non-milk extrinsic sugars, galactose in dietary fibre, cholesterol, phospholipids, betagluten, ginseng, nicotine). No existing fields were removed or renamed.

Aug 18, 2026

Menu API: 5 MB size limit for item images

Item images must now be 5 MB or smaller. Images above this size are not imported. The existing requirements are unchanged: 16:9 aspect ratio, JPEG, white background, recommended 1000 x 562.5.

Aug 17, 2026

Order API: item discount fields corrected to exclude option-level discounts

Documentation update.

subtotal_basket_discounts and subtotal_item_discounts on an Order V2 item report only the discounts allocated to the base item. They exclude discounts allocated to the item's options, which are reported separately in subtotal_options_basket_discounts and subtotal_options_item_discounts.

The API has always behaved this way. The previous documentation incorrectly stated that these fields included option-level discounts. If you built item-level discount reconciliation against the old description, your totals were double-counting option discounts and should be re-checked.

Aug 12, 2026

Large Assortment Integration Guide and Assisted Assortment Integration guides are published.

Aug 6, 2026

Large Assortment: product and category schema clarifications

Documentation update.

  • color and size have been removed from the Product schema.

  • A product name must contain at least one entry, including a translation in the brand's configured primary language.

  • A Category must contain either items or subcategories, never both. The two fields are mutually exclusive, and a subcategory may only contain items.

  • image_url on both Product and Category now documents its image requirements: 16:9 aspect ratio, JPEG, white background, recommended size 1000 x 562.5.

Aug 5, 2026

Venue API: last_three_orders_status returns newest first

last_three_orders_status now returns the venue's most recent order first.

Jul 29, 2026

Large Assortment: file schemas now documented

New documentation.

The two file formats used by Large Assortment integrations are now published on the developer portal, under Large Assortment in the API reference. Neither format was documented before.

  • Product Catalog — an NDJSON file uploaded at brand level. Each line is a Product object describing one product in the variety sold across all of the brand's locations.

  • Assortment — a JSON file uploaded at venue level, mapping 1:1 to a venue. It defines the categories and subcategories, the listings placed in them, and the store-specific attributes such as pricing, stock and availability.

Both schemas are documented in full, including product nutrition and regulatory information, translations, discounts, deposits, purchase limits, sell-by-weight items and picking areas. Each format comes with a complete worked example.

Jul 27, 2026

Menu API: vat_percentage required on deposits

vat_percentage is now a required field on the Deposit schema, alongside price. Send the VAT percentage for every deposit — typically the same rate as the item being sold.

Jul 24, 2026

Menu API: required fields documented across several schemas

Documentation update.

Fields that were always mandatory in practice are now marked required in the spec:

  • Nutrient amount objects: value, plus unit where the object carries one.

  • Caffeine content: serving_size and value.

  • Discounted: original_price and discount_type.

  • ItemV2: delivery_methods.

  • selection_range on multi-choice options and option values: both max and min.

No behaviour changed. If your payloads already validated against the API, they still do.

Jul 9, 2026

Order API: deposits on substitute items

Substitute items in replace-items accept an optional deposit field, for bottle and container deposits on menu-item-replacement and adhoc-replacement. You can either send the bare item price in price with the deposit in deposit, or bundle the deposit into price and omit deposit — but not both, which would double-count it. The deposit's currency must match the order currency.

Jul 8, 2026

Menu API: scheduled discounts

Item updates accept a new scheduled_discount object with starts_at and ends_at timestamps, so a discounted_price applies only inside a chosen window. At least one of the two must be provided; when both are set, starts_at must precede ends_at, the window must span at least 10 minutes, and ends_at must not be in the past. Scheduling a discount requires discounted_price (and therefore price) to be set.

On the read side, the menu response's Discounted object exposes the matching start_date and end_date.

Availability is controlled per country, so check with your integration contact whether scheduled discounts are enabled for your markets.

Jun 16, 2026

Menu API: item images withdrawn from item updates, and per-field support for full-assortment venues

Documentation update.

  • image_url has been removed from the documented item-update payload. Item images are no longer supported through this endpoint; use the menu upload instead.

  • Item-update fields now state whether they are supported for venues on a full-assortment (Large Assortment) integration. Supported: price, discounted_price, enabled, in_stock. Not supported: vat_percentage, disabled_until. On the identifier side, external_id and sku are supported — external_id must be the listing_id from the assortment file, and sku must match the assortment file's sku — while gtin is not supported.

Jun 11, 2026

Order API: campaigns_applied on Order V2

Order V2 exposes campaigns_applied, listing the venue campaigns applied to an order. Only campaigns sponsored wholly or partly by the merchant are included. Each entry carries the campaign's ID, version, name, optional merchant-defined external ID, type, whether it is loyalty-conditioned, and the per-row discount allocation (row_number, count, total_discount).

Three response states are worth handling separately: a non-empty array means campaigns were applied; an empty array means there is nothing to expose (either none applied or all were Wolt-sponsored); and null means campaign information could not be resolved for that order, which is transient and retriable.

Jun 2, 2026

Menu API: asynchronous menu retrieval, richer categories, and stricter identifiers

Documentation update.

  • Get venue menu is now documented as asynchronous. The request returns 202 Accepted with a GetMenuRequestResponse carrying request_id and resource_url. Polling resource_url returns a GetMenuResponse with a status of PENDING, READY, or ERROR, an optional error, and the menu once ready. The endpoint has always worked this way; the spec previously described it as a synchronous 200.

  • Categories gained fields: description, image_url, subcategory_ids, and parent_category_id.

  • inventory is now documented as required on inventory updates. Null is not accepted, where the spec previously said it meant "set to 0".

  • Item and inventory updates require exactly one of external_id, gtin, or sku per item. Previously the wording allowed any of them, which was ambiguous.

  • Option value updates require external_id. gtin and sku are not accepted as identifiers when patching option values.

  • ItemV2 gained discounted, inventory_mode, and vat_percentage.

Jun 1, 2026

Order API: DELIVERY_NOTE document type

Document upload links support a new DELIVERY_NOTE type, for a document describing the contents and details of a delivery.

May 29, 2026

Order API: order-status prerequisites for document upload links

Documentation update.

Creating a document upload link now documents which order statuses are eligible; ineligible requests return 400 Bad Request.

  • Most document types require the order to be ready or delivered.

  • Correction documents (INVOICE_CORRECTION, ALCOHOL_SALE_CORRECTION) are additionally allowed while the order is rejected, so a correction can still be issued for a refunded or returned order.

  • ALCOHOL_SALE_CORRECTION additionally requires that an ALCOHOL_SALE document was already uploaded for the order.

May 27, 2026

Order API: FeePart.type values corrected to lowercase

Documentation update.

The FeePart.type enum was documented in uppercase but the API returns lowercase. The spec now lists the actual values — type_base_delivery, type_service_fee, type_delivery_distance_extra, type_small_order_surcharge, type_venue_campaign_surcharge, type_discount_delivery, type_priority_delivery_fee — and adds type_discount_basket, a basket discount distributed proportionally across fees. The list is still not exhaustive and may be extended.

If you match on this field, check that you are comparing against lowercase values.

May 15, 2026

Order API: GET /orders/{orderId} may lag behind replace-items

Documentation update.

Item replacement is processed asynchronously. The 202 from replace-items confirms the request was accepted, but GET /orders/{orderId} and its V2 equivalent may keep returning the original items for a short period afterwards. Allow a short delay before re-fetching.

Apr 27, 2026

Order API: name optional on price reductions and menu substitutions

name is now optional for reduced-price and menu-item-replacement replacements — if omitted, the item name is resolved from the barcode. It remains required for adhoc-replacement, where no menu lookup is possible. As a consequence, barcode is required for reduced-price whenever name is omitted.

The price field's meaning is also now spelled out: for menu-item-replacement and adhoc-replacement it is the price of the substitute item; for reduced-price it is the new reduced price of the original item.

Apr 24, 2026

Menu API: explicit nesting levels for sub-options

Documentation update.

sub_options no longer references the Option schema recursively. Each nesting level now has its own schema — NestedOptionL1, NestedOptionL2, NestedOptionL3 and their matching value schemas — which makes the three-level limit explicit and renders correctly in the documentation. values is now marked required on Option and on every nested option schema. No payload changes are needed; this documents the sub-options support released in January.

Apr 9, 2026

Order API: OTC batch IDs required for Poland pharmacy orders

For Polish pharmacy venues, mark-order-ready requires a request body when the order contains over-the-counter items. The OrderReadyRequest body carries type (POLAND_PHARMA) and one entry per OTC row number, each with the batch or lot IDs covering that item's quantity. Requests that omit the body, or omit batch IDs for any OTC row, are rejected with 400 Bad Request. This does not apply to other venues or to orders without OTC items.

Mar 27, 2026

Order API: replace-items advanced features now generally available

Weighted item substitution (picked_weight, weighted_item_input_type), free and promotional item additions (item_additions), and multi-SKU substitution have all graduated from incubating and request-only access to generally available. You no longer need to contact support to use them.

The replace-items documentation was rewritten around seven worked scenarios — complete missing item, partial missing with and without a substitute, partial substitution, adhoc replacement, price override, and weight change — each with a full request example.

Mar 20, 2026

Order API: free item additions identified by barcode or name

item_additions no longer takes item_id, which has been removed. Instead:

  • Menu items: send barcode alone. Wolt looks the item up in the venue's menu and resolves the item ID. If the barcode is not in the menu, the request fails.

  • Adhoc items: send name alone. The item is added as a custom, non-menu item.

Free items are always added at price 0. A new optional row_number links a free item to an existing order row, so operations tooling can show why it was added — for example a free drink that came with the meal on row 0.

Feb 11, 2026

Order API: free item additions and weighted-item substitution (on request)

replace-items accepts a new item_additions array for adding free or promotional items without replacing existing ones, and substitute items accept picked_weight and weighted_item_input_type for substituting with a weighted item. Multi-SKU substitution (replacing one item with several, such as one 2 L bottle with two 1 L bottles) is also supported.

At this point all three features were available on request only, and weighted substitution was flagged as incubating. Contact Wolt support to request access. The existing weight field with weight-change-replacement, which adjusts the weight of the same item, was unaffected and fully supported.

Feb 9, 2026

Order & Venue API: spec corrected to match the actual API

Documentation update.

A review of the specs against the implementation fixed a number of mismatches. Order API:

  • order-sent-to-pos returns 204 No Content, not 202.

  • Requesting a document upload link that already exists returns 202, not 200.

  • DocumentType gained the missing ALCOHOL_SALE, INVOICE_CORRECTION, and ALCOHOL_SALE_CORRECTION values.

  • Fields that were always returned are now marked required: cash_amount on cash payments, and gross_price and net_price on deposits.

  • courier_tip added to the delivery object, for the tip given to the courier on self-delivery orders.

  • The delivery type field now lists its values: takeaway, homedelivery, and eatin. eatin is deprecated at Wolt — it can appear in a menu but is not supported for consumers.

  • Deposit returns gained validation constraints: unit_count at least 1, total_price_incl_vat greater than zero, vat_percentage between 0 and 100. Refunds accept at most one basket refund.

  • Order V2 items reference SubstitutionSettingsV2. The unused comment field was removed from the V1 substitution settings. row_number and weight_details are no longer marked required, and both are documented as applying to retail item types only.

Venue API:

  • isOpen renamed to is_open, matching what the API actually serializes.

  • The unused pre_order_prep_time_duration field was removed.

  • 403 Forbidden documented on authenticated endpoints, along with 404 and 503 where they can occur. The 406 response, which is never returned, was removed.

Feb 4, 2026

Venue API: order_handling_configuration

Documentation update.

The venue object exposes order_handling_configuration, describing how the venue handles incoming orders. It carries acceptance_by_wolt (whether the venue uses Wolt's auto-accept, so orders are accepted without manual action) and using_courier_arrival_notification (whether the venue is subscribed to notifications when a courier is approaching or has arrived for pickup). The field has been returned since May 2025 and is only now documented.

Jan 29, 2026

Menu API: nested sub-options and finer selection limits

  • Options support max_same_selections (how many times the same value may be chosen) and max_free_selections (how many selections are free of charge).

  • Option values support sub_options: options hidden until that value is chosen, useful for modifier groups that only apply after an earlier selection. Up to 3 sub-options per value, nested up to 3 levels total.

  • sub_option_values is deprecated in favour of sub_options. The two cannot be combined in the same payload; validation rejects payloads that do.

  • Option values support visible_to_merchant. Setting it to false hides the chosen value from the merchant app and from Order API payloads, for information that is a no-op for store staff. Defaults to true.

Dec 30, 2025

VAT validation for menu uploads As of 30 December 2025, we have introduced additional validation for Menu uploads (Create menu API). If more than 5% of items in a menu upload contain invalid VAT rates, the upload will be rejected with a 406 (Not Acceptable) response. A VAT rate is considered invalid if it does not match any rate permitted by the applicable local legislation. This change helps ensure data accuracy and compliance across all menus.

Jan 24, 2025

  • Order API payload supports a group order’s participants information

    • Once supported, Group order information helps venue to printing a separate label per person in order