Inbound File Feed

The ERP-to-Claret file feed: a set of CSV files delivered on a regular cadence to keep Claret's master and transactional data in sync with your source systems.

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	Locations, location areas, and bins/vessels in one file
Finished Good Items	FG items with the full hierarchy flattened across columns
Bulk Wine Items	Bulk WIP items with the full hierarchy flattened across columns
Crops	Crop master (varietal groups + crop grades) used as recipe ingredients
Recipes	FG / bulk-wine ↔ ingredient mapping (bulk wines and/or crops)

Transactional data

File	What it contains
Inventory	Bulk and finished-goods on-hand snapshot
Bottling Schedule	Planned bottling runs
Work Plans	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.

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.

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.