> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/integrations/inbound-file-feed/recipes.md).

# Recipes

Master data file mapping each finished good or bulk wine item to its ingredient components. One row per ingredient; a blend produces multiple rows sharing the same fg\_item\_name.

Maps each **finished-good or bulk-wine item** to the **ingredient item(s)** that go into it. One row per ingredient. A recipe with multiple ingredient components (a blend) is represented as multiple rows sharing the same `fg_item_name` and yield values.

Ingredients can be:

* Another **bulk wine item** (e.g., a bulk wine going into a bottled FG, or one parent WIP rolling up from its vintages)
* A **crop** / raw grape grade (e.g., a parent WIP composed from multiple grape grades sourced from the farm)

## About the item levels referenced

Unlike [Inventory](/integrations/inbound-file-feed/inventory.md) and [Bottling Schedule](/integrations/inbound-file-feed/bottling-schedule.md), recipes can be defined at **any item level**; there is no strict planning-vs-transactional split. In practice, you'll see recipes at:

* The **Item level** (e.g., `122`): a generic recipe applied to every vintage of that item
* The **Vintage level** (e.g., `122-16`): a vintage-specific recipe that overrides the item-level one for that year
* The **Parent WIP level** (e.g., `ZAMNVCAS`): a recipe describing how a parent bulk wine is produced (e.g., a blend of crops)
* The **Child WIP level** (e.g., `ZAMNVCAS19`): a vintage-specific bulk wine recipe

Deliver recipes at whatever level your ERP maintains them. Claret will match them to the corresponding items in the Items master files.

## Schema

<table><thead><tr><th>#</th><th>Column</th><th data-type="checkbox">Required?</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>1</td><td><code>recipe_type</code></td><td>true</td><td>One of: <code>Strategic, with items only</code>, <code>Operational, with items only</code>, <code>Strategic, with item at locations</code>. Most bottling recipes are <code>Strategic, with items only</code>. See Controlled vocabularies below for definitions.</td><td><code>Strategic, with items only</code></td></tr><tr><td>2</td><td><code>fg_item_name</code></td><td>true</td><td>The finished good produced by this recipe. Must match a name from the Finished Good Items file at any level (<code>item_name</code> or <code>vintage_name</code>) or from the Bulk Wine Items file (<code>parent_wip_name</code> or <code>child_wip_name</code>) if the recipe targets a bulk wine.</td><td><code>122-16</code></td></tr><tr><td>3</td><td><code>yield_quantity</code></td><td>true</td><td>Quantity of finished good produced per recipe execution. Numeric value. Decimals fine, whole numbers fine. No thousands separators.</td><td><code>1</code></td></tr><tr><td>4</td><td><code>yield_uom</code></td><td>true</td><td>Unit of measure for <code>yield_quantity</code>.</td><td><code>9LE Case</code></td></tr><tr><td>5</td><td><code>bulk_item_name</code></td><td>true</td><td>The ingredient item. Must match a <code>parent_wip_name</code> or <code>child_wip_name</code> from the Bulk Wine Items file, or a <code>crop_name</code> from the Crops file.</td><td><code>ZAMNVCAS16</code></td></tr><tr><td>6</td><td><code>bulk_quantity</code></td><td>true</td><td>Quantity of the ingredient consumed per recipe execution. Numeric value. Decimals fine, whole numbers fine. No thousands separators.</td><td><code>2.378</code></td></tr><tr><td>7</td><td><code>bulk_uom</code></td><td>true</td><td>Unit of measure for <code>bulk_quantity</code>. May differ from <code>yield_uom</code> (e.g., crops measured in <code>Ton</code>, wine in <code>Gallon</code>, cases in <code>9LE Case</code>).</td><td><code>Gallon</code></td></tr><tr><td>8</td><td><code>location_name</code></td><td>false</td><td>The location associated with this recipe row. Must match a <code>location</code> from the Locations file. Behavior depends on <code>recipe_type</code>: for <code>Strategic, with items only</code>, leave blank; for <code>Operational, with items only</code>, required and identifies where the recipe is run (all ingredient rows of the same recipe carry the same location); for <code>Strategic, with item at locations</code>, may be populated per ingredient row to identify where each ingredient is sourced (typically a vineyard or other crop location).</td><td><code>ZAM-WINERY</code></td></tr><tr><td>9</td><td><code>waste_factor</code></td><td>false</td><td>Expected waste/loss as a fraction (e.g., <code>0.02</code> = 2%). Numeric value, decimal between 0 and 1. Defaults to <code>0</code> if omitted.</td><td><code>0.02</code></td></tr></tbody></table>

## Header row

```
recipe_type,fg_item_name,yield_quantity,yield_uom,bulk_item_name,bulk_quantity,bulk_uom,location_name,waste_factor
```

## Sample data

```csv
recipe_type,fg_item_name,yield_quantity,yield_uom,bulk_item_name,bulk_quantity,bulk_uom,location_name,waste_factor
"Strategic, with items only",122,1,"9LE Case",ZAMNVCAS,2.3800,Gallon,,0
"Strategic, with items only",122-16,1,"9LE Case",ZAMNVCAS16,2.3776,Gallon,,0
"Strategic, with items only",122-17,1,"9LE Case",ZAMNVCAS17,2.3776,Gallon,,0
"Strategic, with items only",122-18,1,"9LE Case",ZAMNVCAS18,2.3776,Gallon,,0
"Operational, with items only",122-19,1,"9LE Case",ZAMNVCAS19,2.3776,Gallon,ZAM-WINERY,0
"Strategic, with item at locations",ZAMNVCAS,1,Gallon,CAS-A,0.5000,Gallon,,0
"Strategic, with item at locations",ZAMNVCAS,1,Gallon,CAS-B,0.2500,Gallon,,0
"Strategic, with item at locations",ZAMNVCAS,1,Gallon,CAS-C,0.2500,Gallon,,0
"Strategic, with item at locations",CLMCCPIN21,1,Gallon,CAS-A,1.0000,Ton,,0
```

{% hint style="info" %}

* Row 1: an **Item-level** (planning-level) Strategic recipe, a generic recipe for `122` referencing the parent WIP `ZAMNVCAS`.
* Rows 2-4: **Vintage-level** Strategic recipes that override the item-level recipe for the 2016-2018 vintages of `122` (each from its same-year child WIP).
* Row 5: an **Operational** recipe for `122-19` pinned to a specific location (`ZAM-WINERY`). The `location_name` is required on Operational recipe rows; it identifies where the recipe is run.
* Rows 6-8: a **crop-blend recipe** (Strategic, with item at locations). One Gallon of the parent WIP `ZAMNVCAS` is composed from three Cabernet grape grades: `CAS-A` (50%), `CAS-B` (25%), `CAS-C` (25%).
* Row 9: a **child-WIP recipe** sourced from a single crop. One Gallon of `CLMCCPIN21` from 1 Ton of `CAS-A`. Note the unit mix (Ton of crop yielding Gallons of wine).
  {% endhint %}

## Snapshot semantics

* Full snapshot every delivery. Include every active recipe.
* One row per ingredient. A blend with N components produces N rows.
* All rows of the same recipe must share identical values for `recipe_type`, `fg_item_name`, `yield_quantity`, `yield_uom`, and `location_name`.
* A recipe is uniquely identified by (`fg_item_name`, `recipe_type`, `location_name`). Re-delivering the same key with different ingredients replaces the prior recipe atomically.
* A recipe omitted from a new snapshot is treated as retired.

## Controlled vocabularies

### Recipe types

`recipe_type` must be one of:

| Recipe type                         | When to use it                                                                                                                                                                                            |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Strategic, with items only`        | Default for most bottling recipes. Components are items, and the recipe is not tied to a specific location (the same recipe can be run anywhere).                                                         |
| `Operational, with items only`      | Same component shape, but the recipe **is** tied to a location; the `location_name` column becomes required.                                                                                              |
| `Strategic, with item at locations` | Used when components are tracked at specific source locations (e.g., bulk wine in a particular winery's tank farm). The recipe header does not require a location, but each ingredient row may carry one. |