> 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/locations.md).

# Locations

Master data file describing the location hierarchy: Locations → Location Areas → Bins (vessels and tanks). One row per entity, with the hierarchy expressed via a parent\_name reference.

A single combined file describing the location hierarchy: **Locations → Location Areas → Bins (vessels/tanks)**. One row per entity. The hierarchy is expressed via a `parent_name` reference.

## 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>entity_type</code></td><td>true</td><td>One of: <code>location</code>, <code>location_area</code>, <code>bin</code>. Identifies which level of the hierarchy this row represents.</td><td><code>bin</code></td></tr><tr><td>2</td><td><code>name</code></td><td>true</td><td>Identifier. Must be unique within its <code>entity_type</code>.</td><td><code>SS-01</code></td></tr><tr><td>3</td><td><code>parent_name</code></td><td>true</td><td>Required for <code>location_area</code> and <code>bin</code>. The parent's <code>name</code>. For <code>location_area</code>, the parent is a <code>location</code>. For <code>bin</code>, the parent is a <code>location_area</code>. Empty for <code>location</code> rows.</td><td><code>North</code></td></tr><tr><td>4</td><td><code>description</code></td><td>false</td><td>Human-readable description.</td><td><code>Stainless Steel Tank 01</code></td></tr><tr><td>5</td><td><code>bin_type</code></td><td>false</td><td>Only used when <code>entity_type=bin</code>. One of: <code>FG-BIN</code>, <code>Vessel-Stainless</code>, <code>Vessel-Barrel</code>.</td><td><code>Vessel-Stainless</code></td></tr><tr><td>6</td><td><code>external_system_id</code></td><td>false</td><td>Only used when <code>entity_type=bin</code>. The client's internal identifier for the bin.</td><td><code>BIN-1001</code></td></tr></tbody></table>

## Header row

```
entity_type,name,parent_name,description,bin_type,external_system_id
```

## Sample data

```csv
entity_type,name,parent_name,description,bin_type,external_system_id
location,ZAM-WINERY,,"ZAM Apps Winery",,
location,ZAM-WHS,,"ZAM Apps Warehouse",,
location,ZAM-PARTNER,,"ZAM Partner Warehouse",,
location_area,North,ZAM-WINERY,"North Tank Farm",,
location_area,South,ZAM-WINERY,"South Tank Farm",,
location_area,Storage,ZAM-WHS,Storage,,
location_area,"South Storage Building",ZAM-PARTNER,"Storage Building in Southern Area",,
bin,SS-01,North,"Stainless Steel Tank 01",Vessel-Stainless,BIN-1001
bin,SS-02,North,"Stainless Steel Tank 02",Vessel-Stainless,BIN-1002
bin,SS-03,North,"Stainless Steel Tank 03",Vessel-Stainless,BIN-1003
bin,FG-GEN-BIN,Storage,"Finished Good Generic Holding Bin",FG-BIN,BIN-2001
bin,Refrigerator,"South Storage Building","Large Refrigerator",FG-BIN,BIN-3001
```

## Snapshot semantics

* Full snapshot every delivery. Include every active location, area, and bin.
* A `location` row must appear before any `location_area` that references it; a `location_area` row must appear before any `bin` that references it. Order rows accordingly so a single forward-pass parser will validate cleanly.
* Names must be unique within their `entity_type`.
* Renames are not supported in-place. To rename, deliver the new name as a new row.