How to load and update your data

The same fields, with the same names and the same rules, work in the file you upload in the portal, in the API and in the scheduled feed. Column headers are recognised in six languages and by the field name, so the same file works whatever language your staff uses. Which way is available today, family by family, is in the table at the end of this page and on each family page.

From the portal: you upload a CSV or Excel file, see a preview (valid rows, rows to fix with number and reason, what will change) and confirm. From the API: your system sends batches of up to 500 items with an Idempotency-Key, so a repeated call does nothing twice. Scheduled feed: you give us the address of your file and we read it every day.

Every file, batch or feed updates what it carries and deletes nothing: a file with only code and price changes the prices and leaves size, packs and offers as they were. In the API a field sent as null is removed.

«This file is the whole catalog»: the products that are on sale and that the file does not carry are withdrawn (switched off, never deleted: orders that mention them stay readable). The preview tells you how many first, and you confirm with that number. Safety gate: if the file carries less than 90% of the products on sale, nothing is withdrawn and the answer says so: a truncated file does not empty your catalog. A withdrawn product that comes back in a later file is on sale again.

Freshness: declare how often you update prices and stock (declared_refresh_hours); beyond twice that time without updates, the catalog is flagged as stale (GET /v1/catalog/freshness).

Products → prices and stock → offers → zones → windows → closures → customers → order history. A file that refers to a code not loaded yet gives an error on that row, not on the whole file.

CSV with the semicolon separator, UTF-8 (the templates have the BOM, so Excel opens accents correctly); or the Excel workbook. Decimals with comma or point, the same in the whole file. Units only with symbols: kg, g, l, ml, cl, pz. Yes/no: yes, no, sì, 1, 0. Dates YYYY-MM-DD or DD/MM/YYYY. Rows that start with # are not imported: they are the descriptions and the examples of the template.

Every error says the row, the column, the field, a stable code (the same in file, API and portal) and a message in your language. Wrong rows do not stop the good ones: the good rows are written, the others are listed with their reason, and you fix only those.

API keys are test or live, and they separate the data: a test key sees only the test catalog, customers and orders. Load and check everything in test; the portal moves the test products to the open store when you open to customers.