Large Assortment Integration Guide

Large Assortment Integration is an SFTP-based integration designed for partners managing large catalogs, ranging from hundreds to tens of thousands of products. 

Instead of updating items one by one, you manage your entire inventory at scale by uploading two structured files. This gives you full control to list, remove, or organise products while handling complex retail requirements like nutritional data, legal restrictions, and variable weights.

As a user you will maintain two files:

• Product Catalog file (NDJSON) — all your product data: names, descriptions, nutrition, and other attributes. The information stored in the catalog applies to all stores under your company brand.

• Venue Assortment file (JSON) — what's sold in each venue (store), plus operational attributes like product price, stock, and delivery methods.

When to use Large Assortment Integration

Use Large Assortment Integration if:

• You are a retailer managing a large assortment (>500 items per location) across multiple stores.

• You need file-based bulk updates delivered via SFTP.

• You can maintain product data quality and store assortments on an ongoing basis — not just at onboarding stage.

Feasibility checklist

Before onboarding, your Account Manager will run a feasibility check to confirm your data is ready for Large Assortment Integration. Work through this checklist first — if you can't answer “yes” to everything, talk to your Account Manager about what to fix before you start.

Operational expectations

In order to successfully manage a large assortment integration you must:

• Maintain complete, compliant product information, including regulatory attributes in your country of operations. Wolt can't add missing data on your behalf.

• Continuously maintain store-specific assortments, not just at initial setup.

• Keep inventory accuracy high. Inaccurate inventory is the biggest driver of order rejections and high substitutions rates.

Supported structure

Large Assortment Integration supports three levels: category, sub-category, and assortment item (e.g. Dairy products —> Milk —> Organic Lactose-free milk 1L). Sub-categories are optional but strongly recommended — large categories (over 50 items) get hard to browse without them.

Understanding a product

Every item in your Product Catalog is a product, identified by two fields: external_id and, optionally, gtin_barcode. Take time to familiarize yourself with the concept, as it's core to a successful Large Assortment Integration.

• external_id is yours to define — it's how Large Assortment Integration recognises the same product across catalog uploads. It's not shown in the Wolt Listing Manager UI.

• gtin_barcode is your product's GS1 barcode, shown in the Listing Manager UI as the item's GTIN (also known as EAN). A product without one is a “GTIN-less” product. 

• Once a product is created, neither external_id nor gtin_barcode can be changed and a product can't switch between having a GTIN and being GTIN-less. If a later upload sends a different value for either field, that change is ignored. You can always check which items didn’t pass validation in the Log Explorer.

  Identifiers

  Get your identifiers right before you launch.  If you need to change a product's GTIN, or give a GTIN-less product a barcode later, you'll need to create a brand-new product with a new external_id — you can't edit the existing one. Pick stable, never-reused identifiers from day one.

  → See the Product Catalog schema.

Setting up your assortment (creation)

Getting your first files into Large Assortment Integration is a one-time setup.

1. Set up SFTP access. Generate an SSH key pair (OpenSSH format) and share the public key with your Technical Account Manager. They'll send you your SFTP login credentials.

2. Connect to your dedicated SFTP folder.

3. Upload your Product Catalog file once, with your full product range.

4. Wait about 15 minutes for it to process.

5. Upload your Venue Assortment file(s).

6. Check Log Explorer (development or production). Request access from your Technical Account Manager to confirm everything processed as expected.

Keeping assortment up to date (management)

Once you're live, Large Assortment Integration is an ongoing maintenance commitment, not a one-time task.

• Venue Assortment: update whenever product price, stock, or availability changes — daily is typical.  If your systems refresh actual current stock levels and\or pricing on a recurring interval with actual updates - use that interval (not shorter than 30 minutes).

  • to update stock levels & pricing intra-day for specific items (event-driven for specific SKUs only) use Item Update API; 

• Product Catalog: only re-upload when product data itself changes (new products, updated descriptions, and so on). Don't re-send it with every assortment update — it's unnecessary and slows processing.

• Catalog uploads are full files, not deltas: to add a new product, include it alongside your existing catalog. Large Assortment Integration can't process partial/delta catalog updates.

• Venue assortment uploads are full files, not deltas: the assortment you include in the assortment.json will define the assortment visible on your stores at Wolt Marketplace.

• To delist an item, just remove it from the Venue Assortment file. There's no separate “delete” action. If you omit a product from the catalog file, it will not remove it from the venue assortment, as we still will be able to retrieve product data from our database.

How processing works

Product Catalog (NDJSON)

File requirements:

• One file per your company brand

• Filename: product_catalog.ndjson

• Format: NDJSON — one JSON object per line

• Must end with an empty line

• Path for file upload is /brand_<your_brand_id>/product_catalog

→ See the Product Catalog schema.

Venue Assortment (JSON)

Defines what's sold at a specific venue, plus its operational attributes — pricing, stock, delivery methods, and so on.

File requirements:

• Filename: assortment.json

• Must include the venue_id for the specific store

• Path for file upload is /brand_<your_brand_id>/venue_<venue_id>

→ See the Venue Assortment schema.

Sequencing & data dependencies

Processing is timestamp-based, so order matters, but only in one direction.

• A product must exist in the Product Catalog before it can appear in a Venue Assortment file. If it doesn't, it's silently ignored.

• Always upload your Product Catalog before the Venue Assortment file(s) that reference it.

• Venue Assortment files for different venues don't need to be sequenced against each other, they can be dropped at the same time.

• Recommended onboarding timing: upload the Product Catalog, wait ~15 minutes, then upload Venue Assortment file(s).

Understanding an item in an assortment file listing

An item in the Venue Assortment file (also known as “listing”) is the entry of an item to be listed within a venue's assortment.

• Such a “listing” combines listing-level fields (price, delivery methods, enabled/in_stock, etc.) with the product data it references via product_external_id.

• Once a listing is created, reuse the same listing identifier to update it — don't recreate it under a new key.

• Listing identifier (ITEM-0001 from the example below) isn't shown in the Wolt Listing Manager UI:

"ITEM-0001": {
      "product_external_id": "PRODUCT-0001",
      "sku": "SKU-0001",
      "enabled": true,
      "in_stock": true,
      "delivery_methods": [
        "homedelivery",
        "takeaway"
      ],
      "price": {
        "value": 2.45,
        "vat_percentage": 14
      },
      "discount": {
        "percentage": 10
      },
      "sell_by_weight": {
        "avg_piece_weight": 150
      },
      "purchase_limits": {
        "max_quantity": 30
      },
      "restrictions": {
        "courier_restrictions": [
          "no_cars",
          "no_bikes",
          "no_motorcycles"
        ],
        "listing_restrictions": [
          "age",
          "delivery_handshake",
          "counter"
        ],
        "listing_age_restriction": {
          "limit": 24
        }
      }
    }

How products are matched between files

Product_external_id in the assortment file must exactly equal external_id in the Product Catalog. It is the same identifier, different field name in each file.

Large Assortment Integration and Item & Inventory Update APIs

If you already use Wolt's real-time Item Update and Inventory Update APIs, you can also use them for Large Assortment Integration venues with three conditions:

• The venue must already be onboarded to Large Assortment Integration, meaning a Venue Assortment file has been uploaded before you send any item or inventory updates.

• Both APIs match items by SKU only, using the same sku value defined on the listing in your Venue Assortment file. Listing_id, external_id, pos_id, and gtin are not accepted.

• Every time an assortment file is being pushed, it must reflect the most up-to-date current state of product availability and pricing. Assortment file will overwrite changes made with Item/Inventory API prior to upload.

What you can update:

• Item Update API: enabled, in_stock, price and discounted_price flags.

• Inventory Update API: stock counts, but only once the listing has an inventory field set in your Venue Assortment file (this puts the item into inventory mode).

Both APIs are documented in full in the Retail Assortment Guide. APIs are subject to rate limits:

• Item Update API: 1 request / 15 minutes, only delta updates are accepted.

• Inventory Update API: 1 request / 5 minutes, only delta updates, only delta updates are accepted.

Integration checklist

Here's what the process looks like end to end, from your first conversation to your first live upload.

1. Discuss your assortment and integration options with your Account Manager. They'll help confirm Large Assortment Integration is the right fit for your business.

2. Complete the feasibility check with your Account Manager (see the Feasibility checklist).

3. If you pass the feasibility check and are approved for Large Assortment Integration, you'll be invited to a kick-off session with your designated Technical Account Manager.

4. Review this documentation ahead of the kick-off session and prepare questions.

5. After the kick-off session, your Technical Account Manager will give you full access to the Wolt Development environment.

   1. Sign Integration T&C if you haven't done it in the past.

6. Set up your SFTP connection. Share a public SSH key (OpenSSH-formatted) for your server with your Technical Account Manager. You'll use the matching private key to log in to your SFTP folder on Wolt and drop your files. Once you've shared your public key, your Technical Account Manager will send you your SFTP login credentials.

7. Confirm which environment you're using.

Once you start uploading files, track ingestion status and processing outcomes in the Log Explorer. Access is provisioned by your Technical Account Manager, for both test and production.

Use this Solution Scope Document as a supporting resource in the development phase. Your Technical Account Manager will also assess the quality of your integration using it.

FAQ

What timing should I use to send files?

For initial onboarding: send the Product Catalog first, then your Venue Assortment file(s) about 15 minutes later. For ongoing updates: only re-send the Product Catalog when product data itself changes — don't send it alongside every assortment update. If you can't trigger catalog updates on change events, pick a cadence that matches how often your own catalog refreshes (weekly or monthly is typical; daily works too).

Can I use the Item Update API with Large Assortment Integration?

Yes — see “Large assortment integration and Item & Inventory Update APIs” above for the details and conditions.

Can I use the Inventory Update API with Large Assortment Integration?

Yes, once the listing has an inventory field set in your Venue Assortment file. See “Large assortment integration and Item & Inventory Update APIs” above.

How long until a new Venue Assortment file shows up for customers?

Large assortments (10k+ items) are estimated to process in under ~15 minutes. We recommend sending updates during off-hours.

Can I manage GTIN-less products?

Yes. A GTIN-less product can be used in a Venue Assortment file as long as its listing has the sku field set. A GTIN-less product, however, can never get one later.

Do I need to use sub-categories?

No, they're optional, but recommended once a category holds more than roughly 50 items, since large flat categories get hard for customers to browse.

Categories and sub-categories are entirely partner-defined free text sent with every assortment upload. 

How do I know when processing is done?

Check the Log Explorer for processing status on both your Product Catalog and Venue Assortment uploads.

What happens if a product's GTIN changes but our internal product/material number doesn't?

Wolt treats gtin_barcode and external_id as permanent once a product is created. This holds regardless of why an identifier changes on your side. If a catalog update sends a different gtin_barcode for an external_id that already exists, Wolt ignores the change and keeps the original GTIN on file.

This matters if your internal process reassigns a GTIN without creating a new material/product number, since your external_id — if it's derived from that material number — also won't change, and the GTIN update will simply be dropped. To make the new GTIN take effect, you need to create a brand-new product with a new external_id, then retire the old one by removing it from your Venue Assortment file once its replacement is live.

In practice, this means your integration needs its own way to detect a GTIN reassignment and mint a distinguishable external_id when one happens — for example, deriving external_id from the GTIN itself instead of the material number, or appending a suffix when a reassignment is detected. Talk to your Technical Account Manager if you'd like input on an approach before you build this logic.

Expected Language Codes

The following section documents the expected language codes that must be used for the lang field based on the brand’s country.