# Inbound File Feed

The Inbound File Feed is Claret's standard integration pattern for clients whose ERP system can produce scheduled CSV exports. On an agreed cadence (typically daily, but weekly or otherwise is fine), the ERP drops a set of CSV files into a secure location; Claret picks them up and loads them.

This section contains the complete file specifications. Each spec is self-contained, covering schema, sample data, and snapshot semantics, and can be shared independently with the team building the export on the ERP side.

## File list

Master data must arrive before any transactional data that references it. Within each category, order doesn't matter.

### Master data

| File                                                                          | What it contains                                                       |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Locations](/integrations/inbound-file-feed/locations.md)                     | Locations, location areas, and bins/vessels in one file                |
| [Finished Good Items](/integrations/inbound-file-feed/finished-good-items.md) | FG items with the full hierarchy flattened across columns              |
| [Bulk Wine Items](/integrations/inbound-file-feed/bulk-wine-items.md)         | Bulk WIP items with the full hierarchy flattened across columns        |
| [Crops](/integrations/inbound-file-feed/crops.md)                             | Crop master (varietal groups + crop grades) used as recipe ingredients |
| [Recipes](/integrations/inbound-file-feed/recipes.md)                         | FG / bulk-wine ↔ ingredient mapping (bulk wines and/or crops)          |

### Transactional data

| File                                                                      | What it contains                         |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| [Inventory](/integrations/inbound-file-feed/inventory.md)                 | Bulk and finished-goods on-hand snapshot |
| [Bottling Schedule](/integrations/inbound-file-feed/bottling-schedule.md) | Planned bottling runs                    |
| [Work Plans](/integrations/inbound-file-feed/work-plans.md)               | Work orders / cellar tasks               |

## Common file format

All files in the feed follow the same conventions:

* CSV, UTF-8 encoded
* Comma-delimited
* Header row required (first line, exact column names per each spec)
* Double-quote any field containing whitespace, a comma, a newline, or a double-quote; escape embedded double-quotes as `""`. Quoting whitespace-only fields is technically optional per RFC 4180, but some CSV parsers silently trim leading whitespace after a delimiter; quoting eliminates that ambiguity.

{% hint style="info" %}
Each spec gives the exact header row to use. The order of columns in the header is the order Claret expects in the data rows.
{% endhint %}

## A note on "planning" vs. "transactional" item levels

Several of the files reference items at different levels of the item hierarchy. This is a deliberate split:

* **Planning level** (e.g., the `item_name` of an FG). Used by forward-looking files like the Bottling Schedule. Plans are made at the SKU-family grain.
* **Transactional level** (e.g., the `vintage_name` of an FG, or `child_wip_name` of a bulk wine). Used by Inventory, Recipes, and Work Plans. Actuals always operate on a specific vintage.

The Finished Good Items and Bulk Wine Items specs explain the distinction in detail. If your hierarchy doesn't have a vintage level for some items, that's fine; those items reference the planning level for both purposes.

## Snapshot semantics, in brief

Each spec calls out its own semantics, but the general rules are:

* **Master data files** are full snapshots: omitting a row marks the entity retired.
* **Inventory** is a full snapshot: omitting an emptied bin is fine, but to clear a position, send `quantity=0`.
* **Bottling Schedule** is a full forward-looking snapshot: a plan absent from a new snapshot is cancelled.
* **Work Plans** is the exception: re-deliveries update by `external_system_id`, but a plan absent from today's file is **not** auto-cancelled. To cancel, send the row with `status=Cancelled`.


---

# Agent Instructions: 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.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.