Import and export

What it is

The Import / Export ingredients dialog lets you load your own catalog of custom ingredients from a file (in bulk, without creating them one by one) or download it to keep a copy outside the app.

How to get there

From the ingredient catalog, click the Import / Export button in the header. The dialog has two tabs: Import and Export.

Import

Start with the template

If you don't have a file yet, click Download CSV template (in the prompt "Not sure where to start? Download the template with examples and edit it."). It downloads areacacao-ingredients-template.csv (the file name and the example text follow the interface language), already with the correct header and two example rows (Hazelnut praline and Dark couverture 70%) that you can edit or delete. The column names are always the same, in English.

The template includes these 24 columns (all optional except name):

name, category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit, densityGPerMl, weightPerUnitG, water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol, allergens, notes

How to prepare the CSV

The dialog includes a collapsible How to prepare the CSV? section with the rules. In detail:

• Only name is required. Leave blank any columns you don't have.
• Nutrition values are per 100 g (same as on the sheet).
• Decimal separator: both a period and a comma are accepted (18.50 or 18,50). If you use a comma as the decimal separator, a period is read as a thousands separator (1.234,56 is read as 1,234.56).
• allergens: a list of codes separated by ;. The valid codes are the 14 official EU ones: gluten, crustaceans, eggs, fish, peanuts, soy, milk, nuts, celery, mustard, sesame, sulphites, lupin, molluscs. Any code outside this list is ignored. See EU-14 Allergens.
• Empty allergens = no allergens. If you don't know them yet, write undeclared (sin declarar is also accepted): the sheet keeps its allergens undeclared, which is not the same as "no allergens".
• alcohol: grams of ethanol per 100 g (wines and liqueurs). Empty = no data.
• Micronutrients (vitamins, minerals, cholesterol, caffeine) are not loaded via CSV: they're filled in on the ingredient sheet. (If you need them in a file, use the JSON format, which does preserve them.)

Load the data

You have three ways to provide the content:

• Drag and drop a file onto the zone "Drag a CSV or JSON file here".
• Click Choose file and pick a .csv or .json from your computer.
• Expand Or paste text manually and paste the content directly.

The app detects the format automatically (if the text starts with { or [ it treats it as JSON; otherwise as CSV) and shows it in the Detected format selector, which you can correct by hand if needed. The Detected format and Mode selectors and the buttons appear as soon as there's content loaded.

Choose the mode

The Mode selector decides how the import is applied. Matching against your existing ingredients is done by name (case-insensitive):

Preview and confirm

What gets imported from each row

These fields are recognized: name (required), category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit (default g), densityGPerMl, weightPerUnitG, the 12 nutrition values (water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol), allergens, and notes. Headers are case-insensitive and some aliases are accepted (customCode/custom_code, baseUnit/base_unit/unit). Any column not in the list is ignored without an error.

Errors you'll see:

• A row with no name is skipped and reported as "Row N: Name is missing".
• A malformed file is rejected in full: "The CSV file is empty or has no data rows", "Invalid JSON: …", or "JSON: no 'ingredients' array found".

The server sends these messages in the interface language. In "Invalid JSON: …", the technical detail after the colon comes straight from the JSON parser, usually in English.

Export

In the Export tab ("Download your custom catalog. The JSON format preserves complex structures (macros, allergens); CSV is ideal for editing in Excel/Sheets.") you have two direct-download options. Only your active ingredients are exported (deleted ones are not included).

Export as JSON

"Complete format for backup or migration to another instance." Downloads the full sheet of each ingredient as stored, including what the CSV can't represent: micronutrients (which live inside macros), alternate names, and custom fields. It's the recommended format for backups. The structure is:

{
  "version": 1,
  "exportedAt": "2026-06-01T…Z",
  "count": 12,
  "ingredients": [
    { "id": "ci_…", "name": "…", "macros": { "fat": 42, "vitaminE": 5 }, "allergens": ["nuts"], "altNames": [], "customFields": {} }
  ]
}

Each object in ingredients is the full ingredient sheet (abbreviated here).

Export as CSV

"Flat table to open in Excel/Sheets/Numbers." Downloads a flat table (file custom-ingredients-YYYY-MM-DD.csv) ideal for reviewing or editing in a spreadsheet. The CSV includes the macros but not the micronutrients (for those, use JSON).

CSV columns

The dialog's collapsible CSV columns section lists the 25 columns of the exported file, in this order:

id, name, category, subcategory, brand, supplier, customCode, pricePerKg, baseUnit, densityGPerMl, weightPerUnitG, water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa, alcohol, allergens, notes

The allergens column is a semicolon-separated list (for example gluten;milk); it's empty if the sheet has no allergens and contains undeclared if they're undeclared. The only difference from the import template is the id column (present when exporting, ignored when importing).

Notes and limits

• Round-trip by name. Exporting and re-importing works: matching is by name, so the id column in the exported CSV isn't needed when you re-import.
• CSV vs JSON. Use CSV for quick spreadsheet editing (macros, no micros); use JSON for backups: it's the only format that includes the micronutrients. On re-import, JSON keeps macros and micros, but not the alternate names or the custom fields.
• Size. There's no row cap, but the request is limited to ~5 MB. For very large catalogs, split the file into several imports.
• Privacy. Everything operates on your account catalog; neither import nor export touches the public catalog.

Next steps