Header detection

When NearSt ingests a stock file, it needs to know which columns hold the barcode, price, quantity, and so on. If we can't recognise the header row, we silently fall back to a fixed positional mapping — that's the failure mode this page is really about.

What to use as your header row

Include at least one of these headers, and everything else will be recognised automatically:

• barcode, gtin, or sku for the product identifier
• price
• quantity
• currency (optional)

Matching is case-insensitive and ignores whitespace. Common aliases are accepted — for example, qty, qoh, available, stock, and quantityonhand all map to quantity; msrp and retail price map to price; saleprice maps to promotion_amount; and upc, upccode, and ean map to gtin. If you're using headers that aren't recognised, get in touch — we can either add them to the recognised set or set up a per-POS parsing override for your integration.

The failure mode: silent positional fallback

If your file's header row doesn't contain any recognised header, we assume the file has no header row and fall back to a fixed positional mapping:

Every row in the file — including the first — is then parsed against these positions.

This is the failure mode to watch for. A file whose header row uses column names we don't recognise (headers in another language, or a POS-specific naming scheme like Article_Number,Sales_Price,Units_On_Hand) falls through to the positional fallback. If the column order doesn't match barcode, price, quantity, currency, promotion_amount, the upload will succeed but the values will be parsed into the wrong fields — quantities read as currencies and stripped, prices read as barcodes and rejected, and so on.

None of this looks like a connection failure. The upload appears to succeed but the shop's stock feed is silently wrong.

Recommendations

• Use one of the recognised headers. barcode, gtin, sku, price, quantity are always safe.
• Check the Partner Dashboard after your first upload. It reports the parsed line count and any header warnings. A parsed count of zero after an accepted upload is a strong signal that header detection has fallen back to positional mapping.
• If your POS emits a fixed column order that doesn't match the fallback, get in touch — we can add a per-POS parsing override rather than requiring you to change your file format.