> 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

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. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.claret.app/integrations/inbound-file-feed/recipes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.