> ## Documentation Index > Fetch the complete documentation index at: https://help.mathership.com/llms.txt > Use this file to discover all available pages before exploring further. # CSV Upload > Manually upload POS sales data from CSV files # CSV Upload Use CSV Upload to import POS sales data from a CSV file and convert it into inventory movements. CSV Upload is useful when you do not use a direct POS integration or when sales data comes from another system as an export file. The CSV upload can: * Read sales data from a CSV file * Extract POS item codes from selected columns * Read quantities from a quantity column * Read dates from a date column * Match POS codes to POS mappings * Explode recipe mappings into ingredients * Create inventory ledger entries ## How it works Mathership reads the uploaded CSV file row by row. For each row, Mathership applies the configured CSV rules and extracts sold POS items. The basic flow is: 1. Create a CSV integration 2. Configure CSV rules 3. Create POS mappings 4. Upload a CSV file 5. Mathership reads the file 6. Sold POS items are matched to mappings 7. Ingredient deductions are created in the inventory ledger ## Before you start Make sure you already have: * A company in Mathership * Ingredients created in Mathership * Recipes created if you want to map POS items to recipes * Storage units created * POS mappings configured * A CSV file with sales data ## Create a CSV integration CSV upload uses a POS integration with the integration type `CSV`. To create it: 1. Go to **Manage** → **Integrations** 2. Select **CSV Upload** 3. Create a new CSV integration 4. Configure the data schema rules 5. Save the integration The integration stores the rules that tell Mathership how to read the CSV file. ## CSV rules CSV rules define which columns Mathership should read from the uploaded file. The supported rule type is: | Rule type | Purpose | | ---------------------------- | ----------------------------------- | | `column_values_to_pos_codes` | Reads POS codes from one CSV column | A rule can use: | Field | Meaning | | ------------------------ | ---------------------------------------------------------- | | `source_column` | Column containing the POS code or POS codes | | `quantity_source_column` | Optional column containing the quantity | | `date_source_column` | Optional column containing the sale date | | `delimiter` | Optional separator if one cell contains multiple POS codes | ## Example CSV file A simple CSV file could look like this: | pos\_code | qty | date | | --------------- | --: | ---------- | | BURGER\_CLASSIC | 2 | 2025-10-20 | | COLA\_033 | 4 | 2025-10-20 | | ESPRESSO | 3 | 2025-10-20 | In this example: * `pos_code` is the source column * `qty` is the quantity column * `date` is the date column ## Example rule Example rule configuration: | Setting | Value | | --------------- | ---------------------------- | | Rule type | `column_values_to_pos_codes` | | Source column | `pos_code` | | Quantity column | `qty` | | Date column | `date` | | Delimiter | empty | With this rule, Mathership reads each POS code from the `pos_code` column. ## Multiple POS codes in one cell If one CSV cell contains multiple POS codes, use a delimiter. Example CSV: | pos\_codes | qty | date | | ------------------------- | --: | ---------- | | BURGER\_CLASSIC,COLA\_033 | 1 | 2025-10-20 | Example rule: | Setting | Value | | --------------- | ----------- | | Source column | `pos_codes` | | Quantity column | `qty` | | Date column | `date` | | Delimiter | `,` | Mathership splits the value and processes both POS codes. ## Quantity handling If a quantity column is configured, Mathership uses the value from that column. If no quantity column is configured, Mathership uses `1` as the default quantity. Example: | POS code | Quantity result | | ---------------------------------- | --------------: | | `BURGER_CLASSIC` with qty `2` | 2 sold items | | `COLA_033` without quantity column | 1 sold item | ## Date handling If a date column is configured, Mathership uses that date for the inventory movement. If no date column is configured, Mathership uses the current date and time. The date should be readable as an ISO-style date or datetime, for example: | Format | Example | | ------------- | --------------------- | | Date | `2025-10-20` | | Date and time | `2025-10-20T14:30:00` | ## POS mappings Before uploading sales data, create POS mappings. A POS mapping connects a POS item code or name to a Mathership ingredient or recipe. Examples: | POS code | Mapped object | Quantity | | ---------------- | --------------------- | -------: | | `COLA_033` | Cola bottle | 1 | | `ESPRESSO` | Coffee beans | 0.009 | | `BURGER_CLASSIC` | Classic Burger recipe | 1 | Without mappings, Mathership cannot convert POS sales into inventory deductions. ## Ingredient mapping Use ingredient mapping when a POS item should deduct one ingredient directly. Example: | Sold POS item | Inventory deduction | | -------------- | ---------------------------- | | 1 × `COLA_033` | Deduct 1 Cola bottle | | 1 × `ESPRESSO` | Deduct 0.009 kg coffee beans | ## Recipe mapping Use recipe mapping when a POS item consists of multiple ingredients. Example: | Sold POS item | Mapped to | | ---------------- | --------------------- | | `BURGER_CLASSIC` | Classic Burger recipe | When the CSV file contains `BURGER_CLASSIC`, Mathership explodes the recipe and deducts all recipe ingredients. ## Upload a CSV file To upload a file: 1. Open **Manage** → **Integrations** 2. Open the CSV integration 3. Choose the CSV file 4. Start the upload 5. Review the result The uploaded file must be a CSV file with headers. Mathership reads the column names from the first row. ## What happens during upload When a CSV file is uploaded, Mathership: 1. Reads the CSV file 2. Applies the configured rules to each row 3. Extracts POS codes, quantities, and dates 4. Matches POS codes to POS mappings 5. Explodes recipe mappings into ingredients 6. Calculates ingredient quantities 7. Creates inventory ledger entries 8. Updates the integration's last run time 9. Returns a processing summary ## Upload result A successful upload returns a summary of created inventory deductions. The result can include: * Ingredient name * Deducted quantity * Storage unit * Date of the inventory movement Example result: | Ingredient | Deducted quantity | Storage unit | Date | | ---------- | ----------------: | -------------- | ---------- | | Burger Bun | 12 | Main Storage | 2025-10-20 | | Beef Patty | 12 | Main Storage | 2025-10-20 | | Cola 0.33l | 24 | Drinks Storage | 2025-10-20 | ## Inventory ledger entries CSV uploads create inventory ledger entries with transaction type `ISSUE`. That means the uploaded sales reduce inventory. Each created entry includes: * Company * Ingredient * Storage unit * Transaction type * Quantity * Unit cost * Value * Date See [Inventory Ledger](/restaurants/inventory/inventory-ledger) for details. ## Storage unit selection For CSV uploads, Mathership determines the storage unit from the mapped ingredient or recipe logic. The system tries to resolve a storage unit from: 1. The recipe line issue storage 2. The ingredient preferred issue storage 3. The recipe default issue storage 4. A storage unit with available stock 5. The first available storage unit as fallback For accurate inventory deductions, configure storage settings on ingredients and recipes. ## Common setup order Use this order for a clean CSV setup: 1. Create storage units 2. Create ingredients 3. Create recipes if needed 4. Create the CSV integration 5. Configure CSV rules 6. Create POS mappings 7. Upload a small test CSV 8. Check the inventory ledger 9. Upload the full CSV file ## Test with a small file first Before uploading a large export, test with a small CSV file. Use only a few rows, for example: | pos\_code | qty | date | | --------------- | --: | ---------- | | COLA\_033 | 1 | 2025-10-20 | | BURGER\_CLASSIC | 1 | 2025-10-20 | After upload, check whether: * The upload completed successfully * The correct ingredients were deducted * The quantities are correct * The correct storage units were used * The ledger entries have the correct date ## Common errors ### File not provided This happens when no CSV file was attached. Upload a CSV file and try again. ### CSV integration not found This happens when the selected integration does not exist or is not a CSV integration. Check that: * The integration exists * The integration belongs to the selected company * The integration type is `CSV` ### Processing exceptions This happens when Mathership finds problems during processing. Common causes are: * POS code has no mapping * Recipe has a cycle * Storage unit cannot be resolved * Ingredient no longer exists * Recipe line is incomplete Fix the mappings or recipe setup and upload again. ### Unmapped POS code This means the CSV file contains a POS code that has no POS mapping. Example: | Problem | Fix | | ---------------------------------- | ----------------------------------------- | | `unmapped_pos_code:BURGER_CLASSIC` | Create a POS mapping for `BURGER_CLASSIC` | ### Wrong quantity Check: * The quantity column in the CSV * The configured quantity source column * The POS mapping quantity * The recipe line quantities * The base unit of the ingredient ### Wrong date Check: * The date column in the CSV * The configured date source column * Whether the date format can be read correctly If the date cannot be read, Mathership may use the current date and time. ## Best practices * Use stable POS codes instead of product names if possible * Keep CSV headers consistent * Avoid changing column names after setup * Test with a small file first * Map high-volume POS items first * Use recipes for prepared dishes * Use direct ingredient mappings for simple items * Review the inventory ledger after every first upload * Keep a copy of uploaded CSV files for traceability ## Example CSV setup Example CSV headers: | Column | Purpose | | -------------- | ------------- | | `article_code` | POS code | | `quantity` | Sold quantity | | `sold_at` | Sale date | Example rule: | Setting | Value | | --------------- | ---------------------------- | | Rule type | `column_values_to_pos_codes` | | Source column | `article_code` | | Quantity column | `quantity` | | Date column | `sold_at` | | Delimiter | empty | Example mappings: | POS code | Mapping type | Mapped to | Quantity | | ---------------- | ------------ | -------------- | -------: | | `COLA_033` | Ingredient | Cola 0.33l | 1 | | `ESPRESSO` | Ingredient | Coffee beans | 0.009 | | `BURGER_CLASSIC` | Recipe | Classic Burger | 1 | ## Related pages Map POS codes to ingredients or recipes. Return to the integrations overview. Manage storage units used for inventory deductions. Review inventory movements created by CSV uploads.