Import and export

What it is

The Import / Export ingredients modal 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 modal 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, already with the correct header and two example rows (a hazelnut praline and a 70% dark couverture) that you can edit or delete.

The template includes these 23 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, allergens, notes

How to prepare the CSV

The modal includes a How to prepare the CSV? dropdown 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, Spanish format included). If you use a comma as the decimal, the period is read as a thousands separator (1.234,56 is read as one thousand two hundred thirty-four point fifty-six).
• 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.
• 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.

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 11 macros (water, fat, saturatedFat, carbs, sugars, protein, fiber, salt, kcalPer100g, cocoaButterFat, totalCocoa), 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: Falta nombre" (the server returns this message in Spanish regardless of the interface language).
• A malformed file is rejected in full: "CSV vacío o sin filas", "JSON inválido: …", or "JSON: no se encontró array 'ingredients'" (these messages also come from the server in Spanish).

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 modal's CSV columns dropdown lists the 24 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, allergens, notes

The allergens column is a semicolon-separated list (for example gluten;milk). 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