> 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/finished-good-items.md).

# Finished Good Items

Master data file delivering Claret's finished-goods item hierarchy in a single flat file, with every level flattened across columns on each row.

Finished-goods item master. Delivers Claret's full item hierarchy in a single file, with every level flattened across columns on each row.

## About the hierarchy

By default, Claret expects a four-level hierarchy: **Brand Group → Brand → Item → Vintage**. For example:

* **Brand Group:** `Premium`
* **Brand:** `ZAM`
* **Item:** `122` (ZAM Napa Valley Cabernet Sauvignon 12 x 750ml)
* **Vintage:** `122-16`, `122-17`, ... `122-24` (one per vintage year)

**If your item hierarchy differs in either depth or naming, that is fine.** Provide your own level names as column pairs in your hierarchy's order, from highest (most general) to lowest (most granular), using the pattern `{Level} Name, {Level} Description`. Replace `{Level}` with the name of each level you use. Examples:

* Two-level: `Item Name, Item Description, Vintage Name, Vintage Description`
* Three-level: `Brand Name, Brand Description, Item Name, Item Description, Vintage Name, Vintage Description`
* Five-level: `Category Name, Category Description, Brand Group Name, Brand Group Description, Brand Name, Brand Description, Item Name, Item Description, Vintage Name, Vintage Description`

If you adapt the columns to your own hierarchy, email `help@claret.app` describing your levels in order so the labels can be applied in Claret's UI.

## Planning level vs. Transactional level

This is a key concept for the integration. In the default hierarchy, **two of the four levels are referenced by other files**, and they serve different purposes:

| Level                        | Example  | Used as the reference in                                                                                                                                                      | Purpose                                                                             |
| ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Item** (`item_name`)       | `122`    | [Bottling Schedule](/integrations/inbound-file-feed/bottling-schedule.md), supply plans, budgets, forecasts                                                                   | Forward-looking **planning**: "we plan to bottle 1,500 cases of 122 in May"         |
| **Vintage** (`vintage_name`) | `122-16` | [Inventory](/integrations/inbound-file-feed/inventory.md), [Recipes](/integrations/inbound-file-feed/recipes.md), [Work Plans](/integrations/inbound-file-feed/work-plans.md) | Actuals / **transactional** data: "we have 879 cases of 122-16 in FG-GEN-BIN today" |

**Why the split:** Plans are made at the SKU-family grain (you commit to bottling a certain volume of `122` per period), but actual production, inventory, and recipes always operate on a specific vintage (`122-16`), because the wine in the bottle is a particular year's wine.

**Special case: items without a Vintage level.** Some items (e.g., `124` "ZAM Lodi Zinfandel 12 x 750ml" below) don't have vintages. For these, the **Item level** serves as both the planning and the transactional reference, and rows in this file will have the Vintage columns blank. Downstream transactional files for these items should reference the `item_name` directly.

## Schema

One row per leaf-level entry. For items with vintages, that's one row per vintage. For items without vintages, that's one row at the item level with the vintage columns blank.

<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>brand_group_name</code></td><td>true</td><td>Top-level grouping. Same value repeats across every row in that brand group.</td><td><code>Premium</code></td></tr><tr><td>2</td><td><code>brand_group_description</code></td><td>false</td><td>Long-form description of the brand group.</td><td><code>Premium group</code></td></tr><tr><td>3</td><td><code>brand_name</code></td><td>true</td><td>Mid-level grouping. Same value repeats across every row in that brand.</td><td><code>ZAM</code></td></tr><tr><td>4</td><td><code>brand_description</code></td><td>false</td><td>Long-form description of the brand.</td><td><code>ZAM brand</code></td></tr><tr><td>5</td><td><code>item_name</code></td><td>true</td><td><strong>The planning level.</strong> Referenced by Bottling Schedule and other planning files.</td><td><code>122</code></td></tr><tr><td>6</td><td><code>item_description</code></td><td>false</td><td>Long-form description of the item.</td><td><code>ZAM Napa Valley Cabernet Sauvignon 12 x 750ml</code></td></tr><tr><td>7</td><td><code>vintage_name</code></td><td>false</td><td><strong>The transactional level.</strong> Referenced by Inventory, Recipes, and Work Plans. Leave blank if this item has no vintages. <strong>Must be unique across all rows in the file when present.</strong></td><td><code>122-16</code></td></tr><tr><td>8</td><td><code>vintage_description</code></td><td>false</td><td>Long-form description of the vintage.</td><td><code>ZAM Napa Valley Cabernet Sauvignon 12 x 750ml 2016</code></td></tr></tbody></table>

## Header row

```
brand_group_name,brand_group_description,brand_name,brand_description,item_name,item_description,vintage_name,vintage_description
```

## Sample data

```csv
brand_group_name,brand_group_description,brand_name,brand_description,item_name,item_description,vintage_name,vintage_description
Premium,"Premium group",ZAM,"ZAM brand",122,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml",122-16,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml 2016"
Premium,"Premium group",ZAM,"ZAM brand",122,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml",122-17,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml 2017"
Premium,"Premium group",ZAM,"ZAM brand",122,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml",122-18,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml 2018"
Premium,"Premium group",ZAM,"ZAM brand",122,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml",122-19,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml 2019"
Premium,"Premium group",ZAM,"ZAM brand",122,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml",122-20,"ZAM Napa Valley Cabernet Sauvignon 12 x 750ml 2020"
Premium,"Premium group",ZAM,"ZAM brand",123,"ZAM Sonoma Coast Chardonnay 12 x 750ml",,
Premium,"Premium group",ZAM,"ZAM brand",124,"ZAM Lodi Zinfandel 12 x 750ml",,
```

{% hint style="info" %}
Rows 1-5: item `122` has multiple vintages, one row per vintage with parent columns repeated. Rows 6-7: items `123` and `124` have no vintages, single row each with vintage columns blank.
{% endhint %}

## Snapshot semantics

* Full snapshot every delivery. Include every currently-active item and vintage.
* An item or vintage omitted from a new snapshot is treated as retired; its history is preserved but no new transactional rows referencing it will be accepted.
* `item_name` must be unique across all rows. `vintage_name`, when present, must also be unique across all rows.
* All `Name` and `Description` columns should be populated where applicable. `Description` values appear in Claret's UI (tooltips, search, exports) and improve usability for the people working in the grids.