> ## 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.

# Integrations Overview

> Connect Mathership with POS systems and external sales data sources

# Integrations

Connect Mathership with external systems to reduce manual work and keep inventory data up to date.

Integrations are mainly used to:

* Connect POS systems
* Sync locations, stores, products, or items
* Map POS sales to ingredients or recipes
* Transfer sales into inventory movements
* Import POS sales data by CSV when no direct integration is available

<CardGroup cols={3}>
  <Card title="Connect POS systems" icon="plug">
    Connect supported POS systems such as Lightspeed K-Series and Sides POS.
  </Card>

  <Card title="Map sales to inventory" icon="arrows-turn-to-dots">
    Link POS items or products to Mathership ingredients and recipes.
  </Card>

  <Card title="Create ledger movements" icon="list-check">
    Turn mapped POS sales into inventory deductions in the ledger.
  </Card>
</CardGroup>

## Available integrations

<CardGroup cols={3}>
  <Card title="Lightspeed K-Series" icon="bolt" href="/en/restaurants/integrations/lightspeed">
    Connect Lightspeed, sync locations and items, and transfer POS sales into inventory.
  </Card>

  <Card title="Sides POS" icon="cash-register" href="/en/restaurants/integrations/sides-pos">
    Connect Sides, sync stores and products, and process daily sales reports.
  </Card>

  <Card title="CSV Upload" icon="file-csv" href="/en/restaurants/integrations/pos-csv-upload">
    Upload POS sales data manually from a configured CSV file.
  </Card>

  <Card title="POS Mapping" icon="arrows-turn-to-dots" href="/en/restaurants/integrations/pos-mapping">
    Map POS items to ingredients or recipes so sales can update inventory.
  </Card>

  <Card title="Storage Units" icon="warehouse" href="/en/restaurants/inventory/storage-units">
    Manage the storage units used for POS sales transfers and inventory movements.
  </Card>

  <Card title="Ledger" icon="list-check" href="/en/restaurants/inventory/ledger">
    Review inventory movements created by orders, transfers, waste, counts, and POS integrations.
  </Card>
</CardGroup>

## Access integrations

To manage integrations:

<Steps>
  <Step title="Open Manage">
    Go to **Manage** in the Mathership dashboard.
  </Step>

  <Step title="Open Integrations">
    Select **Integrations**.
  </Step>

  <Step title="Choose an integration">
    Select the integration you want to configure, such as **Lightspeed K-Series**, **Sides POS**, or **CSV Upload**.
  </Step>

  <Step title="Connect or update the system">
    Connect the external system, update credentials, or configure CSV import settings.
  </Step>

  <Step title="Sync external data">
    Sync locations, stores, products, or items depending on the integration.
  </Step>

  <Step title="Set up mappings">
    Link POS items or products to Mathership ingredients or recipes.
  </Step>

  <Step title="Activate when ready">
    Activate the integration, location, or store only after storage units and mappings are ready.
  </Step>
</Steps>

## How integrations work

Most POS integrations follow the same basic structure.

<Steps>
  <Step title="Connect the system">
    Lightspeed uses OAuth. Sides uses username and password credentials. CSV Upload uses a configured CSV import.
  </Step>

  <Step title="Sync external data">
    Sync locations, stores, POS items, products, or other data needed for mapping.
  </Step>

  <Step title="Link storage units">
    Each active POS location or store needs a Mathership storage unit. This defines where inventory should be deducted from.
  </Step>

  <Step title="Map POS items">
    POS items and products can be mapped to ingredients or recipes. Recipe mappings are expanded into ingredient movements.
  </Step>

  <Step title="Transfer sales">
    Sales data creates inventory issue movements. Historical migrations can process past sales, and manual transfers can be triggered for specific dates.
  </Step>
</Steps>

## Direct POS integrations

### Lightspeed K-Series

Lightspeed uses an OAuth connection.

After connecting Lightspeed, you can:

* Sync Lightspeed locations
* Link each location to a Mathership storage unit
* Activate locations
* Start a historical migration
* Sync Lightspeed items
* Map items to ingredients or recipes
* Run manual transfers for specific dates
* Pause or resume automatic transfers

See [Lightspeed K-Series](/en/restaurants/integrations/lightspeed) for setup details.

### Sides POS

Sides uses username and password credentials.

After connecting Sides, you can:

* Test the connection
* Sync stores
* Link each store to a Mathership storage unit
* Activate stores
* Start a historical migration
* Sync products
* Map products to ingredients or recipes
* Run manual transfers for specific dates
* Pause or resume automatic transfers

See [Sides POS](/en/restaurants/integrations/sides-pos) for setup details.

## CSV Upload

CSV Upload is used when sales data is imported manually instead of through a live POS connection.

Use CSV Upload to:

* Upload POS sales data from a file
* Process sales from systems without a direct integration
* Apply configured CSV rules
* Create inventory deductions based on mapped POS codes

CSV Upload requires correct POS mappings before sales can be processed.

See [CSV Upload](/en/restaurants/integrations/pos-csv-upload) for setup details.

## POS mapping

POS mapping defines how sales affect inventory.

A POS item can be mapped to:

* **Ingredient** — the ingredient is deducted directly
* **Recipe** — the recipe is broken down into its ingredients
* **Quantity factor** — defines how much inventory is affected per sale

| POS item     | Mapped to  | Result                         |
| ------------ | ---------- | ------------------------------ |
| Cheeseburger | Recipe     | Deducts all recipe ingredients |
| Espresso     | Ingredient | Deducts coffee directly        |
| Bottle Cola  | Ingredient | Deducts one bottle from stock  |

See [POS Mapping](/en/restaurants/integrations/pos-mapping) for details.

## Storage unit mapping

Before a POS location or store can be activated, it must be linked to a storage unit.

This tells Mathership where inventory should be deducted from.

| External system | External location | Mathership storage unit |
| --------------- | ----------------- | ----------------------- |
| Lightspeed      | Main Restaurant   | Main Storage            |
| Lightspeed      | Bar               | Bar Storage             |
| Sides           | Downtown Store    | Kitchen Storage         |

Without a linked storage unit, activation and transfers may fail.

<Warning>
  Always check the linked storage unit before activating a location or store. A wrong storage unit can create inventory movements in the wrong place.
</Warning>

## Historical migration

Some integrations can process historical sales data.

This is useful when:

* You activate a new POS location or store
* You want to import recent sales history
* You added mappings after the integration was created
* You need to rerun a migration after fixing mappings

For Lightspeed and Sides, activation can start a historical migration for the last 90 completed days.

## Manual transfer

Manual transfers let you process sales for a specific date.

Use this when:

* You want to transfer one day manually
* A previous transfer failed
* You updated mappings and want to reprocess sales
* You need to check one specific business day
* You want to test an integration before relying on automatic processing

The transfer creates inventory ledger entries based on mapped POS sales.

<Note>
  Manual transfers are useful for testing because you can check the resulting ledger movements before enabling automatic transfers.
</Note>

## Automatic transfer

Some integrations support automatic sales transfers.

Depending on the integration setup, automatic transfers can be:

| State   | Meaning                                                         |
| ------- | --------------------------------------------------------------- |
| Active  | Sales are processed automatically                               |
| Paused  | Automatic processing is stopped, but setup and history are kept |
| Resumed | Automatic processing can be enabled again later                 |

Use pause if you want to stop automatic inventory deductions temporarily without deleting the integration.

## Common setup workflow

<Steps>
  <Step title="Connect the POS integration">
    Connect Lightspeed, Sides, or configure CSV Upload.
  </Step>

  <Step title="Sync locations or stores">
    Import external locations or stores.
  </Step>

  <Step title="Link storage units">
    Assign each location or store to the correct Mathership storage unit.
  </Step>

  <Step title="Sync POS products or items">
    Import the products or items that need to be mapped.
  </Step>

  <Step title="Create POS mappings">
    Map high-priority POS products or items to ingredients or recipes.
  </Step>

  <Step title="Activate the location or store">
    Activate only after storage units and key mappings are ready.
  </Step>

  <Step title="Review migration status">
    Check whether the historical migration started and completed correctly.
  </Step>

  <Step title="Check the ledger">
    Review created inventory movements.
  </Step>

  <Step title="Run manual transfers if needed">
    Use manual transfers to test or reprocess specific dates.
  </Step>
</Steps>

## Best practices

<CardGroup cols={2}>
  <Card title="Set up storage units first" icon="warehouse">
    Create and check storage units before activating POS locations or stores.
  </Card>

  <Card title="Sync before mapping" icon="rotate">
    Sync products or items before creating mappings.
  </Card>

  <Card title="Start with important items" icon="ranking-star">
    Start with high-volume POS items and products first.
  </Card>

  <Card title="Map carefully" icon="arrows-turn-to-dots">
    Check ingredient, recipe, and quantity factor before saving mappings.
  </Card>

  <Card title="Review unmapped items" icon="magnifying-glass">
    Use unmapped items after the first transfer as a working list.
  </Card>

  <Card title="Check the ledger" icon="list-check">
    Review ledger movements after activation and after major mapping changes.
  </Card>

  <Card title="Rerun only when needed" icon="clock-rotate-left">
    Rerun migrations only after correcting mappings or setup issues.
  </Card>

  <Card title="Keep names clear" icon="tag">
    Keep product and recipe names clear so mappings are easier to maintain.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Integration cannot be connected">
    Check that:

    * Your credentials are correct
    * The external system is available
    * The integration is configured for the correct company
    * You have permission to manage the company
  </Accordion>

  <Accordion title="Location or store cannot be activated">
    Check that:

    * The location or store was synced
    * A storage unit is linked
    * The storage unit belongs to the same company
    * No migration is already running
  </Accordion>

  <Accordion title="Products or items are missing">
    Try syncing products or items again.

    For Sides, products may be loaded from cache unless you manually sync them.

    For Lightspeed, use the item sync option to refresh cached items.
  </Accordion>

  <Accordion title="Sales do not affect inventory">
    Check that:

    * POS items are mapped
    * The mapped ingredient or recipe belongs to the same company
    * The location or store is activated
    * A storage unit is linked
    * The transfer completed successfully
  </Accordion>

  <Accordion title="Inventory numbers look wrong">
    Check:

    * POS mappings
    * Quantity factors
    * Recipe ingredients
    * Storage unit assignment
    * Ledger entries for the affected date
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={3}>
  <Card title="Lightspeed K-Series" icon="bolt" href="/en/restaurants/integrations/lightspeed">
    Connect Lightspeed and transfer POS sales into inventory.
  </Card>

  <Card title="Sides POS" icon="cash-register" href="/en/restaurants/integrations/sides-pos">
    Connect Sides and process daily sales reports.
  </Card>

  <Card title="CSV Upload" icon="file-csv" href="/en/restaurants/integrations/pos-csv-upload">
    Upload POS sales data manually from CSV files.
  </Card>

  <Card title="POS Mapping" icon="arrows-turn-to-dots" href="/en/restaurants/integrations/pos-mapping">
    Map POS products to ingredients or recipes.
  </Card>

  <Card title="Storage Units" icon="warehouse" href="/en/restaurants/inventory/storage-units">
    Set up the storage units used for inventory transfers.
  </Card>

  <Card title="Ledger" icon="list-check" href="/en/restaurants/inventory/ledger">
    Review inventory movements created by integrations.
  </Card>
</CardGroup>