File formats

This page describes the files Omnilinker reads and writes outside the Catalog: the stock import, and the exports from Inventory and Pricing Intelligence. Use it when you generate import files from another system, or read export files with a script. For products, prices, purchase prices and images, see Importing products, prices and images.

​

Stock import

The stock import changes stock levels in bulk from an Excel workbook. Each row adds stock to, or removes stock from, one product in one warehouse, and becomes a stock movement.

​

Before you start

• You need the Import Stock Items permission, under Inventory Management.
• The import is part of Inventory Management. If Inventory Management is not enabled for your organization, it is not available.
• The products must exist in the Catalog, and the warehouses on Inventory > Warehouses, each with a code.

​

Import a file

The import runs in the background. If a row fails while it runs, the other rows still import.

​

File

• An Excel workbook, .xlsx, of at most 5 MB. CSV and older .xls files are not accepted. Split a larger file into several smaller ones.
• The first row is the header row. Data starts in row 2. Through the API, each row’s lineNumber is its row number in the sheet.
• Keep the header names exactly as in the template. They are in English whatever the language of your Omnilinker.

​

Columns

Quantity is a change, not the new stock level: a row with 5 adds five units to whatever is in stock. A positive quantity is saved as a positive adjustment, a negative one as a negative adjustment, on Stock Movements. Example:

​

Why a row is skipped or fails

The window counts invalid and failed rows but does not say why. Check the rows against these rules. A row is invalid, and skipped, when: A valid row fails while the import runs, and the other rows still import, when:

• no product has the SKU (check upper and lower case),
• no warehouse has the code,
• the row would take the stock below zero.

The window refuses a whole file with a message when:

• it is larger than 5 MB: “Excel file exceeds the 5 MB limit. Split it into smaller batches.”
• it is not an Excel workbook: “The file is not a valid Excel (.xlsx) workbook, or it is corrupted. Download the template and try again.”

​

Import stock through the API

The same import is available to an API key with the Import Stock Items permission:

1. POST /api/inventory/stock-import/parse-excel with the workbook as a base64-encoded JSON string. The answer is the preview: rows, each with lineNumber, sku, warehouseCode, quantity, reason, notes and validationError, plus validRowCount and invalidRowCount.
2. POST /api/inventory/stock-import/enqueue-import with { "rows": [ … ] }. Rows with a validationError, or without a SKU or warehouse code, are left out. The answer is the import’s id, and the import runs in the background.

You can also skip the workbook and send rows you build yourself to enqueue-import. Give each row its own lineNumber: Omnilinker uses it to make sure a row is applied once even if the background import is retried. That protection covers one import only: each call to enqueue-import starts a new import, so sending the same rows twice changes the stock twice. To check the result, read the stock levels or the stock movements afterwards; the progress of an import is not available through the API. GET /api/inventory/stock-import/import-template returns the template.

​

Exports

Exports are Excel workbooks unless noted. Column headers are in English. Times are in UTC, written as yyyy-MM-dd HH:mm:ss unless noted. When an export would go over its limit, narrow the filters first. The stock exports stop at the limit; the other exports refuse to start and say how many rows the filters match. Exporting the filtered offers also needs at least one active filter: “Export requires at least one active filter. Please narrow your query before exporting.” Exporting needs the export permission of the page, such as Export Stock Items and Export Stock Movements under Inventory Management. The Catalog’s exports are described in Importing products, prices and images, and the price history’s CSV download in Price history.

​

Stock levels

One row per product and warehouse. Sheet name: Stock Levels. Product SKU, Product Name, Brand, Category, Warehouse, On Hand, Reserved, Reserved (ERP), Available, On Order, In Transit, Reorder Point, Safety Stock, Max Stock Level, Reorder Quantity, Status, Discontinued, Notes. Status is one of InStock, LowStock, OutOfStock, NoStock or Overstock. Quantities have up to four decimal places.

​

Stock movements

One row per movement. Sheet name: Stock Movements. Date, Product SKU, Product Name, Warehouse, Movement Type, Quantity, Running Balance, Reference Number, Reason, Source Warehouse Id, Destination Warehouse Id, Lot Number, Serial Number, Notes. Date is when the movement was recorded, in UTC. Movement Type is one of Receipt, Shipment, AdjustmentPositive, AdjustmentNegative, TransferOut, TransferIn, Reservation, ReservationRelease, Return, Scrap, CountAdjustment, InitialStock, ErpSync or ExternalSync. The warehouse ids of a transfer are GUIDs.

​

Offers

Sheet name: Offers Export. Product Name, SKU, GTIN, Merchant, Data Source, Current Price, Currency, Availability, Reference Price, Reference Currency, Basis Level, Basis Origin, Price Difference (%), Price Difference, Last Update, External Offer ID, Offer URL, Created Date. See Offers for what the reference price and the difference mean.

​

Product overview

Sheet name: Product Overview Export. Product Name, SKU, GTIN, Brand, Comparison Price, Purchase Price, Offer Currency, Reference Currency, Purchase Currency, Total Offers, Available Offers, Not Available Offers, Total Violations, Lowest Price, Average Price, Highest Price, Median Price, Price Deviation (%), Below Market (%), Tracking Status, Last Update, Created Date, Merchants, Has No Offers, Has Stale Data. See Product overview.

​

Price gaps

The Export gaps window of the manufacturer dashboard offers three formats: Excel, CSV and Evidence pack (one CSV per reseller plus a summary, zipped). Excel and CSV have the same columns. Excel puts them on a sheet named Gaps: Product, SKU, GTIN, Reseller, Authorised seller, Source, Market, Price, Currency, Reference, Reference currency, Reference level, Deviation %, Difference, Band, Gap since (UTC), Availability. Options under Include add columns or a sheet:

• Offer URL and scrape time for every row adds Offer URL and Seen at (UTC).
• Who moved first, and case status adds Moved first, Case and Case status.
• A sheet with the … offers that cannot be compared (Excel only) adds a second sheet, Not comparable, with Product, SKU, Reseller, Source, Market, Price, Currency, Why it cannot be compared, Reference currency, Reference level and Seen at (UTC).

Authorised seller holds Yes or No, and Moved first holds Yes or nothing. Times are in ISO 8601, in UTC. Gap since (UTC) starts with before when the gap was already open where the price history Omnilinker keeps begins. The CSV file is meant for other tools and scripts:

• UTF-8 with a byte order mark.
• Comma-separated, with CRLF line ends. A value with a comma, a quote or a line break is put in double quotes, and a quote inside it is doubled.
• Numbers use a dot for decimals and no thousands separator, whatever your language: prices with two decimals, Deviation % with one.
• A text value that starts with =, +, - or @ gets a leading ', so a spreadsheet does not run it as a formula. Strip it if your script needs the original text.

The evidence pack is a ZIP file with:

• one CSV per reseller, named after the reseller’s domain and the date, with the columns Product, SKU, GTIN, Reference price level, Recommended price, Currency, Price in the shop, Difference (%), Checked at (UTC), Source and Offer link;
• summary.txt, which states the scope, when the pack was made, the reference price level per market, the tolerance and the counts;
• not-comparable.csv, when you tick A file with the … offers that cannot be compared.

The two column options above do not change the evidence pack’s files. See Overview, price map and gaps.