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

# POS Mapping

> Map POS items to ingredients or recipes so sales can create inventory movements

# POS Mapping

POS mappings tell Mathership what should happen when a POS item is sold.

A POS item can be mapped to:

* An ingredient
* A recipe

Mappings are used by all POS integrations:

* Lightspeed K-Series
* SIDES POS

Without POS mappings, Mathership can receive or import sales data, but it cannot reliably turn those sales into inventory movements.

<CardGroup cols={3}>
  <Card title="Map ingredients" icon="carrot">
    Deduct one ingredient directly when a simple POS item is sold.
  </Card>

  <Card title="Map recipes" icon="utensils">
    Expand a sold POS item into recipe ingredients and deduct them from inventory.
  </Card>

  <Card title="Review unmapped items" icon="magnifying-glass">
    Use unmapped POS items as a working list for missing mappings.
  </Card>
</CardGroup>

<CardGroup cols={3}>
  <Card title="Map ingredients" icon="carrot">
    Deduct one ingredient directly when a simple POS item is sold.
  </Card>

  <Card title="Map recipes" icon="utensils">
    Expand a sold POS item into recipe ingredients and deduct them from inventory.
  </Card>

  <Card title="Review unmapped items" icon="magnifying-glass">
    Use unmapped POS items as a working list for missing mappings.
  </Card>
</CardGroup>

## What POS mapping does

When a POS transfer runs, Mathership reads the sold POS items and checks whether each item has a mapping.

If a mapping exists, Mathership creates inventory movements.

| POS item    | Mapping                  | Inventory result              |
| ----------- | ------------------------ | ----------------------------- |
| Espresso    | Ingredient: Coffee beans | Deduct coffee beans           |
| Cola 0.33 l | Ingredient: Cola bottle  | Deduct bottles                |
| Burger      | Recipe: Burger recipe    | Deduct all recipe ingredients |

If no mapping exists, the item is skipped or reported as unmapped.

The sale can be visible in the transfer result, but it will not reduce inventory until a mapping exists.

## Why mappings are required

POS systems usually know what was sold. Mathership needs to know what inventory should change because of that sale.

| POS sale        | What Mathership needs to know                    |
| --------------- | ------------------------------------------------ |
| 1 × Espresso    | How many kg of coffee beans should be deducted   |
| 1 × Cola 0.33 l | Which bottle ingredient should be deducted       |
| 1 × Burger      | Which recipe should be exploded into ingredients |

The POS item name alone is not enough. A mapping connects the external POS item to the correct Mathership inventory object.

## Mapping types

| Mapping type | Use when                                                |
| ------------ | ------------------------------------------------------- |
| Ingredient   | The sold POS item should deduct one ingredient directly |
| Recipe       | The sold POS item consists of several ingredients       |

Use ingredient mappings for simple items.

Use recipe mappings for prepared dishes, drinks, menus, or anything made from multiple ingredients.

## Mapping to an ingredient

Use an ingredient mapping when one sold POS item should deduct one ingredient directly.

| POS item         | Ingredient   | Quantity |
| ---------------- | ------------ | -------: |
| Cola 0.33 l      | Cola bottle  |        1 |
| Espresso         | Coffee beans |    0.009 |
| Wine glass 0.2 l | House wine   |      0.2 |

The quantity defines how much of the ingredient is deducted per sold POS item.

**sold quantity × mapping quantity = ingredient deduction**

If **Espresso** is mapped to **Coffee beans** with quantity `0.009`:

| Sold          | Mapping quantity | Deduction |
| ------------- | ---------------: | --------: |
| 1 × Espresso  |         0.009 kg |  0.009 kg |
| 5 × Espresso  |         0.009 kg |  0.045 kg |
| 20 × Espresso |         0.009 kg |   0.18 kg |

## Mapping to a recipe

Use a recipe mapping when one sold POS item consists of multiple ingredients.

| POS item         | Recipe                  |
| ---------------- | ----------------------- |
| Burger           | Burger recipe           |
| Pizza Margherita | Pizza Margherita recipe |
| Caesar Salad     | Caesar Salad recipe     |
| Espresso Martini | Espresso Martini recipe |

When the POS item is sold, Mathership expands the recipe and deducts all ingredients from the recipe lines. This also supports sub-recipes.

| POS item    | Mapping                  | Inventory result              |
| ----------- | ------------------------ | ----------------------------- |
| Espresso    | Ingredient: Coffee beans | Deduct coffee beans           |
| Cola 0.33 l | Ingredient: Cola bottle  | Deduct bottles                |
| Burger      | Recipe: Burger recipe    | Deduct all recipe ingredients |

If no mapping exists, the item is skipped or reported as unmapped.

The sale can be visible in the transfer result, but it will not reduce inventory until a mapping exists.

## Why mappings are required

POS systems usually know what was sold. Mathership needs to know what inventory should change because of that sale.

| POS sale        | What Mathership needs to know                    |
| --------------- | ------------------------------------------------ |
| 1 × Espresso    | How many kg of coffee beans should be deducted   |
| 1 × Cola 0.33 l | Which bottle ingredient should be deducted       |
| 1 × Burger      | Which recipe should be exploded into ingredients |

The POS item name alone is not enough. A mapping connects the external POS item to the correct Mathership inventory object.

## Mapping types

| Mapping type | Use when                                                |
| ------------ | ------------------------------------------------------- |
| Ingredient   | The sold POS item should deduct one ingredient directly |
| Recipe       | The sold POS item consists of several ingredients       |

Use ingredient mappings for simple items.

Use recipe mappings for prepared dishes, drinks, menus, or anything made from multiple ingredients.

## Mapping to an ingredient

Use an ingredient mapping when one sold POS item should deduct one ingredient directly.

| POS item         | Ingredient   | Quantity |
| ---------------- | ------------ | -------: |
| Cola 0.33 l      | Cola bottle  |        1 |
| Espresso         | Coffee beans |    0.009 |
| Wine glass 0.2 l | House wine   |      0.2 |

The quantity defines how much of the ingredient is deducted per sold POS item.

**sold quantity × mapping quantity = ingredient deduction**

If **Espresso** is mapped to **Coffee beans** with quantity `0.009`:

| Sold          | Mapping quantity | Deduction |
| ------------- | ---------------: | --------: |
| 1 × Espresso  |         0.009 kg |  0.009 kg |
| 5 × Espresso  |         0.009 kg |  0.045 kg |
| 20 × Espresso |         0.009 kg |   0.18 kg |

## Mapping to a recipe

Use a recipe mapping when one sold POS item consists of multiple ingredients.

| POS item         | Recipe                  |
| ---------------- | ----------------------- |
| Burger           | Burger recipe           |
| Pizza Margherita | Pizza Margherita recipe |
| Caesar Salad     | Caesar Salad recipe     |
| Espresso Martini | Espresso Martini recipe |

When the POS item is sold, Mathership expands the recipe and deducts all ingredients from the recipe lines. This also supports sub-recipes.

Example:

**Burger → Burger recipe → bun, patty, cheese, sauce, salad**

If 3 burgers are sold, Mathership calculates the ingredient requirement for 3 recipe portions and creates inventory deductions for each ingredient.

## Quantity multiplier

The quantity field is a multiplier.

For ingredient mappings, it defines how much of the ingredient is deducted per sold POS item.

For recipe mappings, it defines how many recipe portions are used per sold POS item.

<Tabs>
  <Tab title="Ingredient quantity">
    **sold quantity × mapping quantity = ingredient deduction**

    | Sold            | Mapping quantity | Deduction |
    | --------------- | ---------------: | --------: |
    | 3 × Cola        |         1 bottle | 3 bottles |
    | 5 × Espresso    |         0.009 kg |  0.045 kg |
    | 10 × Wine glass |            0.2 l |       2 l |
  </Tab>

  <Tab title="Recipe quantity">
    **sold quantity × mapping quantity = recipe portions**

    | Sold              | Mapping quantity | Recipe portions |
    | ----------------- | ---------------: | --------------: |
    | 2 × Burger        |                1 |      2 portions |
    | 1 × Party platter |                4 |      4 portions |
    | 3 × Small salad   |              0.5 |    1.5 portions |
  </Tab>
</Tabs>

Use `1` when one sold POS item equals one recipe portion. Use another value when the POS item represents more or less than one recipe portion.

## Subtraction mappings

Mappings can use `is_subtraction`.

In the mapping sheet, this appears as the **Is subtraction** toggle.

This is used for removal modifiers — items that indicate something was not included in a sale.

| POS item        | Use case                                            |
| --------------- | --------------------------------------------------- |
| No chips        | Reverse a chip deduction when chips were not served |
| Refund item     | Reverse a previous deduction                        |
| Correction item | Reduce or offset a POS quantity                     |

Only use this when the POS item should not behave like a normal sale deduction.

<Warning>
  Review subtraction mappings carefully. Incorrect subtraction logic can create inventory movements in the wrong direction.
</Warning>

## Where to create mappings

Mappings are created directly from the item or product list inside each integration.

There is no separate mapping management page.

## The mapping sheet

The mapping sheet opens as a side panel. The header shows the current mapping status and item details from the POS system.

| Integration | Fields shown in header                                        |
| ----------- | ------------------------------------------------------------- |
| Lightspeed  | Item name, Item ID, SKU, Price                                |
| SIDES       | Product name, External ID, Article number, Type, Kitchen name |

### Mapping form fields

| Field          | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| Map type       | Toggle between **Recipe** and **Ingredient** — switching resets the target selection |
| Target         | Search and select the ingredient or recipe to map to                                 |
| Quantity       | How much inventory is affected per sold unit — defaults to `1.0`                     |
| Is subtraction | Toggle for removal modifiers — reverses the inventory direction                      |

## Lightspeed item mappings

Lightspeed items are synced from Lightspeed K-Series.

Mathership stores the mapping using the Lightspeed item name.

| Lightspeed item | Mapping type | Mapped to             | Quantity |
| --------------- | ------------ | --------------------- | -------: |
| Espresso        | Ingredient   | Coffee beans          |    0.009 |
| Cola 0.33 l     | Ingredient   | Cola bottle           |        1 |
| Classic Burger  | Recipe       | Classic Burger recipe |        1 |

## SIDES product mappings

SIDES products are synced from the SIDES product API.

Mappings are stored at integration level, not per store. One product mapping applies across all stores of the same integration.

| SIDES product | Mapping type | Mapped to           | Quantity |
| ------------- | ------------ | ------------------- | -------: |
| Cheeseburger  | Recipe       | Cheeseburger recipe |        1 |
| Fries         | Recipe       | Fries recipe        |        1 |
| Bottle Water  | Ingredient   | Water bottle        |        1 |

## Editing a mapping

Click an already-mapped item row. The mapping sheet opens pre-filled with the current values.

Update any field and click **Save changes**.

## Deleting a mapping

Click the mapped item row, then click **Delete mapping** in the bottom left of the sheet.

Confirm the deletion in the dialog.

After deletion, future sales of that item will no longer affect inventory until it is mapped again.

<Warning>
  Deleting a mapping does not reverse past inventory movements. To correct previous postings, re-run the affected transfer or create correcting inventory movements.
</Warning>

Before deleting a mapping, check whether the POS item is still sold.

If it is still active, deleting the mapping will cause future sales to become unmapped.

## Mapping state in the item list

| State      | Meaning                                               |
| ---------- | ----------------------------------------------------- |
| Mapped     | The item has an active mapping                        |
| Not mapped | The item has no mapping and will not affect inventory |

The **Mapped to** column shows the target ingredient or recipe name, the quantity, and a subtraction indicator if applicable.

Use the **Mapped** filter in the toolbar to show only unmapped items.

## Storage unit selection

The mapping defines what should be deducted. The storage unit defines where it should be deducted.

Depending on the integration, the storage unit comes from:

* The linked Lightspeed location
* The linked SIDES store
* Recipe issue storage
* Ingredient issue storage
* Fallback storage logic

For Lightspeed and SIDES, make sure the location or store is linked to the correct storage unit before activation or transfer.

| External location | Storage unit    | Result                              |
| ----------------- | --------------- | ----------------------------------- |
| Bar POS           | Bar Storage     | Drinks are deducted from bar stock  |
| Restaurant POS    | Main Kitchen    | Food is deducted from kitchen stock |
| Terrace POS       | Terrace Storage | Terrace sales deduct terrace stock  |

If no storage unit can be resolved, Mathership cannot create a correct inventory deduction.

## Recipe processing

When a POS item is mapped to a recipe, Mathership calculates the required ingredient quantities from the recipe lines.

The recipe logic considers:

* Quantity per portion
* Mapping quantity
* Sold quantity
* Trim percentage
* Sub-recipes
* Ingredient storage rules

If a recipe contains another recipe, Mathership expands the sub-recipe as well.

Example:

<Info>
  Burger recipe → Burger bun → Beef patty → Sauce recipe → Mayonnaise, Ketchup, Spices
</Info>

If the burger is sold, Mathership also processes the sauce recipe.

## Trim percentage

Recipe lines can include a trim or loss percentage. This is used when more raw ingredient is required than the final usable amount.

| Ingredient | Required usable amount | Trim percentage | Inventory deduction |
| ---------- | ---------------------: | --------------: | ------------------: |
| Tomato     |                 1.0 kg |             10% |            1.111 kg |
| Onion      |                 1.0 kg |             20% |             1.25 kg |

If trim percentage is configured incorrectly, the transfer reports an `invalid_trim_pct` exception.

## Preventing recipe cycles

Recipes should not reference themselves directly or indirectly.

<Warning>
  Bad example: Burger recipe → Sauce recipe → Burger recipe
</Warning>

This creates a recipe cycle. A recipe cycle would cause endless expansion, so Mathership stops processing and records a `recipe_cycle` exception.

## Unmapped POS items

An unmapped POS item is a sold item that has no mapping.

| Sold POS item     | Result                |
| ----------------- | --------------------- |
| Espresso          | Processed if mapped   |
| Cola 0.33 l       | Processed if mapped   |
| New seasonal item | Skipped if not mapped |

Unmapped items are common during setup. Use them as a worklist for missing mappings.

After creating missing mappings, reprocess the affected date or rerun a migration.

## Common mapping errors

| Error                  | Meaning                                         |
| ---------------------- | ----------------------------------------------- |
| `recipe_not_found`     | The selected recipe does not exist              |
| `ingredient_not_found` | The selected ingredient does not exist          |
| `validation_error`     | Required mapping data is missing or invalid     |
| `unauthorized_access`  | The mapping does not belong to the current user |
| `unmapped_pos_item`    | A POS item was sold but no mapping exists       |
| `recipe_cycle`         | A recipe references itself through recipe lines |
| `invalid_trim_pct`     | A recipe line has an invalid trim percentage    |
| `no_issue_storage`     | No storage unit could be resolved               |
| `negative_stock`       | The deduction would create negative stock       |

## Mapping checklist

Before activating a POS transfer, check:

* Important POS products are synced
* Every relevant sales item is mapped
* Recipes contain correct ingredient lines
* Quantities are realistic
* Units are correct
* Storage units are linked
* One test transfer has been reviewed in the inventory ledger

## Good mapping examples

**Burger → Burger recipe → bun, patty, cheese, sauce, salad**

If 3 burgers are sold, Mathership calculates the ingredient requirement for 3 recipe portions and creates inventory deductions for each ingredient.

## Quantity multiplier

The quantity field is a multiplier.

For ingredient mappings, it defines how much of the ingredient is deducted per sold POS item.

For recipe mappings, it defines how many recipe portions are used per sold POS item.

<Tabs>
  <Tab title="Ingredient quantity">
    **sold quantity × mapping quantity = ingredient deduction**

    | Sold            | Mapping quantity | Deduction |
    | --------------- | ---------------: | --------: |
    | 3 × Cola        |         1 bottle | 3 bottles |
    | 5 × Espresso    |         0.009 kg |  0.045 kg |
    | 10 × Wine glass |            0.2 l |       2 l |
  </Tab>

  <Tab title="Recipe quantity">
    **sold quantity × mapping quantity = recipe portions**

    | Sold              | Mapping quantity | Recipe portions |
    | ----------------- | ---------------: | --------------: |
    | 2 × Burger        |                1 |      2 portions |
    | 1 × Party platter |                4 |      4 portions |
    | 3 × Small salad   |              0.5 |    1.5 portions |
  </Tab>
</Tabs>

Use `1` when one sold POS item equals one recipe portion. Use another value when the POS item represents more or less than one recipe portion.

## Subtraction mappings

Mappings can use `is_subtraction`.

In the mapping sheet, this appears as the **Is subtraction** toggle.

This is used for removal modifiers — items that indicate something was not included in a sale.

| POS item        | Use case                                            |
| --------------- | --------------------------------------------------- |
| No chips        | Reverse a chip deduction when chips were not served |
| Refund item     | Reverse a previous deduction                        |
| Correction item | Reduce or offset a POS quantity                     |

Only use this when the POS item should not behave like a normal sale deduction.

<Warning>
  Review subtraction mappings carefully. Incorrect subtraction logic can create inventory movements in the wrong direction.
</Warning>

## Where to create mappings

Mappings are created directly from the item or product list inside each integration.

There is no separate mapping management page.

## The mapping sheet

The mapping sheet opens as a side panel. The header shows the current mapping status and item details from the POS system.

| Integration | Fields shown in header                                        |
| ----------- | ------------------------------------------------------------- |
| Lightspeed  | Item name, Item ID, SKU, Price                                |
| SIDES       | Product name, External ID, Article number, Type, Kitchen name |

### Mapping form fields

| Field          | Description                                                                          |
| -------------- | ------------------------------------------------------------------------------------ |
| Map type       | Toggle between **Recipe** and **Ingredient** — switching resets the target selection |
| Target         | Search and select the ingredient or recipe to map to                                 |
| Quantity       | How much inventory is affected per sold unit — defaults to `1.0`                     |
| Is subtraction | Toggle for removal modifiers — reverses the inventory direction                      |

## Lightspeed item mappings

Lightspeed items are synced from Lightspeed K-Series.

Mathership stores the mapping using the Lightspeed item name.

| Lightspeed item | Mapping type | Mapped to             | Quantity |
| --------------- | ------------ | --------------------- | -------: |
| Espresso        | Ingredient   | Coffee beans          |    0.009 |
| Cola 0.33 l     | Ingredient   | Cola bottle           |        1 |
| Classic Burger  | Recipe       | Classic Burger recipe |        1 |

## SIDES product mappings

SIDES products are synced from the SIDES product API.

Mappings are stored at integration level, not per store. One product mapping applies across all stores of the same integration.

| SIDES product | Mapping type | Mapped to           | Quantity |
| ------------- | ------------ | ------------------- | -------: |
| Cheeseburger  | Recipe       | Cheeseburger recipe |        1 |
| Fries         | Recipe       | Fries recipe        |        1 |
| Bottle Water  | Ingredient   | Water bottle        |        1 |

## Editing a mapping

Click an already-mapped item row. The mapping sheet opens pre-filled with the current values.

Update any field and click **Save changes**.

## Deleting a mapping

Click the mapped item row, then click **Delete mapping** in the bottom left of the sheet.

Confirm the deletion in the dialog.

After deletion, future sales of that item will no longer affect inventory until it is mapped again.

<Warning>
  Deleting a mapping does not reverse past inventory movements. To correct previous postings, re-run the affected transfer or create correcting inventory movements.
</Warning>

Before deleting a mapping, check whether the POS item is still sold.

If it is still active, deleting the mapping will cause future sales to become unmapped.

## Mapping state in the item list

| State      | Meaning                                               |
| ---------- | ----------------------------------------------------- |
| Mapped     | The item has an active mapping                        |
| Not mapped | The item has no mapping and will not affect inventory |

The **Mapped to** column shows the target ingredient or recipe name, the quantity, and a subtraction indicator if applicable.

Use the **Mapped** filter in the toolbar to show only unmapped items.

## Storage unit selection

The mapping defines what should be deducted. The storage unit defines where it should be deducted.

Depending on the integration, the storage unit comes from:

* The linked Lightspeed location
* The linked SIDES store
* Recipe issue storage
* Ingredient issue storage
* Fallback storage logic

For Lightspeed and SIDES, make sure the location or store is linked to the correct storage unit before activation or transfer.

| External location | Storage unit    | Result                              |
| ----------------- | --------------- | ----------------------------------- |
| Bar POS           | Bar Storage     | Drinks are deducted from bar stock  |
| Restaurant POS    | Main Kitchen    | Food is deducted from kitchen stock |
| Terrace POS       | Terrace Storage | Terrace sales deduct terrace stock  |

If no storage unit can be resolved, Mathership cannot create a correct inventory deduction.

## Recipe processing

When a POS item is mapped to a recipe, Mathership calculates the required ingredient quantities from the recipe lines.

The recipe logic considers:

* Quantity per portion
* Mapping quantity
* Sold quantity
* Trim percentage
* Sub-recipes
* Ingredient storage rules

If a recipe contains another recipe, Mathership expands the sub-recipe as well.

Example:

<Info>
  Burger recipe → Burger bun → Beef patty → Sauce recipe → Mayonnaise, Ketchup, Spices
</Info>

If the burger is sold, Mathership also processes the sauce recipe.

## Trim percentage

Recipe lines can include a trim or loss percentage. This is used when more raw ingredient is required than the final usable amount.

| Ingredient | Required usable amount | Trim percentage | Inventory deduction |
| ---------- | ---------------------: | --------------: | ------------------: |
| Tomato     |                 1.0 kg |             10% |            1.111 kg |
| Onion      |                 1.0 kg |             20% |             1.25 kg |

If trim percentage is configured incorrectly, the transfer reports an `invalid_trim_pct` exception.

## Preventing recipe cycles

Recipes should not reference themselves directly or indirectly.

<Warning>
  Bad example: Burger recipe → Sauce recipe → Burger recipe
</Warning>

This creates a recipe cycle. A recipe cycle would cause endless expansion, so Mathership stops processing and records a `recipe_cycle` exception.

## Unmapped POS items

An unmapped POS item is a sold item that has no mapping.

| Sold POS item     | Result                |
| ----------------- | --------------------- |
| Espresso          | Processed if mapped   |
| Cola 0.33 l       | Processed if mapped   |
| New seasonal item | Skipped if not mapped |

Unmapped items are common during setup. Use them as a worklist for missing mappings.

After creating missing mappings, reprocess the affected date or rerun a migration.

## Common mapping errors

| Error                  | Meaning                                         |
| ---------------------- | ----------------------------------------------- |
| `recipe_not_found`     | The selected recipe does not exist              |
| `ingredient_not_found` | The selected ingredient does not exist          |
| `validation_error`     | Required mapping data is missing or invalid     |
| `unauthorized_access`  | The mapping does not belong to the current user |
| `unmapped_pos_item`    | A POS item was sold but no mapping exists       |
| `recipe_cycle`         | A recipe references itself through recipe lines |
| `invalid_trim_pct`     | A recipe line has an invalid trim percentage    |
| `no_issue_storage`     | No storage unit could be resolved               |
| `negative_stock`       | The deduction would create negative stock       |

## Mapping checklist

Before activating a POS transfer, check:

* Important POS products are synced
* Every relevant sales item is mapped
* Recipes contain correct ingredient lines
* Quantities are realistic
* Units are correct
* Storage units are linked
* One test transfer has been reviewed in the inventory ledger

## Good mapping examples

| POS item      | Good mapping                             | Why                                     |
| ------------- | ---------------------------------------- | --------------------------------------- |
| Cola 0.33 l   | Ingredient: Cola bottle, quantity 1      | Simple packaged item                    |
| Espresso      | Ingredient: Coffee beans, quantity 0.009 | Direct ingredient deduction             |
| Burger        | Recipe: Burger recipe, quantity 1        | Prepared dish with several ingredients  |
| Party platter | Recipe: Platter recipe, quantity 4       | One sale equals several recipe portions |

## Poor mapping examples

| Problem                                       | Why it is risky                                   |
| --------------------------------------------- | ------------------------------------------------- |
| Mapping every dish directly to one ingredient | Recipe ingredients will be missing                |
| Using unclear POS names                       | Hard to maintain mappings                         |
| Using wrong quantity factors                  | Inventory deductions become too high or too low   |
| No storage unit linked                        | Transfer cannot deduct from the correct place     |
| Recipes without ingredient lines              | Recipe sales create no useful inventory movements |

## Updating mappings

Mappings can be changed at any time. After changing mappings, you may need to reprocess historical data.

<Tabs>
  <Tab title="Lightspeed">
    * Use **Manual Transfer** for one date
    * Use **Re-run Migration** for a wider historical period
  </Tab>

  <Tab title="SIDES">
    * Use **Manual Transfer** for one date
    * Use **Re-run Migration** if historical bill positions should be processed again
  </Tab>
</Tabs>

## Testing a mapping

To test a mapping:

<Steps>
  <Step title="Choose a POS item">
    Choose one POS item with known sales.
  </Step>

  <Step title="Confirm the mapping exists">
    Confirm that the POS item is mapped.
  </Step>

  <Step title="Check the target">
    Confirm that the mapped ingredient or recipe is correct.
  </Step>

  <Step title="Check the quantity factor">
    Confirm that the quantity factor is correct.
  </Step>

  <Step title="Run a manual transfer">
    Run a manual transfer for one date.
  </Step>

  <Step title="Open the inventory ledger">
    Review the created inventory movement.
  </Step>

  <Step title="Compare the result">
    Compare the deducted quantity with the expected quantity.
  </Step>
</Steps>

| Test item       | Expected result                            |
| --------------- | ------------------------------------------ |
| 10 × Espresso   | 0.09 kg coffee beans deducted              |
| 5 × Cola 0.33 l | 5 bottles deducted                         |
| 2 × Burger      | Ingredients for 2 burger portions deducted |

## Best practices

<CardGroup cols={2}>
  <Card title="Start with top sellers" icon="ranking-star">
    Start with the most frequently sold POS items.
  </Card>

  <Card title="Use recipes for dishes" icon="utensils">
    Use recipes for prepared dishes, drinks, menus, and items with multiple ingredients.
  </Card>

  <Card title="Use ingredients for simple items" icon="carrot">
    Use direct ingredient mappings for simple packaged items.
  </Card>

  <Card title="Keep POS names stable" icon="tag">
    POS item name changes can break mappings.
  </Card>

  <Card title="Check quantities carefully" icon="calculator">
    Wrong quantity factors make inventory deductions too high or too low.
  </Card>

  <Card title="Test before automation" icon="clipboard-check">
    Test one date manually before enabling automation.
  </Card>

  <Card title="Review unmapped items" icon="magnifying-glass">
    Review unmapped items after the first transfer.
  </Card>

  <Card title="Check the ledger" icon="list-check">
    Check the inventory ledger after every major mapping change.
  </Card>
</CardGroup>

<Warning>
  Do not delete mappings unless the POS item should no longer be processed.
</Warning>

## Related pages

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

  <Card title="Sides POS" icon="plug" href="/en/restaurants/integrations/sides-pos">
    Connect Sides POS and sync stores and products.
  </Card>

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

  <Card title="Inventory Ledger" icon="list-check" href="/en/restaurants/inventory/inventory-ledger">
    Review inventory movements created from POS transfers.
  </Card>
</CardGroup>

## Poor mapping examples

| Problem                                       | Why it is risky                                   |
| --------------------------------------------- | ------------------------------------------------- |
| Mapping every dish directly to one ingredient | Recipe ingredients will be missing                |
| Using unclear POS names                       | Hard to maintain mappings                         |
| Using wrong quantity factors                  | Inventory deductions become too high or too low   |
| No storage unit linked                        | Transfer cannot deduct from the correct place     |
| Recipes without ingredient lines              | Recipe sales create no useful inventory movements |

## Updating mappings

Mappings can be changed at any time. After changing mappings, you may need to reprocess historical data.

<Tabs>
  <Tab title="Lightspeed">
    * Use **Manual Transfer** for one date
    * Use **Re-run Migration** for a wider historical period
  </Tab>

  <Tab title="SIDES">
    * Use **Manual Transfer** for one date
    * Use **Re-run Migration** if historical bill positions should be processed again
  </Tab>
</Tabs>

## Testing a mapping

<Steps>
  <Step title="Choose a POS item">
    Choose one POS item with known sales.
  </Step>

  <Step title="Confirm the mapping exists">
    Confirm that the POS item is mapped.
  </Step>

  <Step title="Check the target">
    Confirm that the mapped ingredient or recipe is correct.
  </Step>

  <Step title="Check the quantity factor">
    Confirm that the quantity factor is correct.
  </Step>

  <Step title="Run a manual transfer">
    Run a manual transfer for one date.
  </Step>

  <Step title="Open the inventory ledger">
    Review the created inventory movement.
  </Step>

  <Step title="Compare the result">
    Compare the deducted quantity with the expected quantity.
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Start with top sellers" icon="ranking-star">
    Start with the most frequently sold POS items.
  </Card>

  <Card title="Use recipes for dishes" icon="utensils">
    Use recipes for prepared dishes, drinks, menus, and items with multiple ingredients.
  </Card>

  <Card title="Use ingredients for simple items" icon="carrot">
    Use direct ingredient mappings for simple packaged items.
  </Card>

  <Card title="Keep POS names stable" icon="tag">
    POS item name changes can break mappings.
  </Card>

  <Card title="Check quantities carefully" icon="calculator">
    Wrong quantity factors make inventory deductions too high or too low.
  </Card>

  <Card title="Test before automation" icon="clipboard-check">
    Test one date manually before enabling automation.
  </Card>

  <Card title="Review unmapped items" icon="magnifying-glass">
    Review unmapped items after the first transfer.
  </Card>

  <Card title="Check the ledger" icon="list-check">
    Check the inventory ledger after every major mapping change.
  </Card>
</CardGroup>

<Warning>
  Do not delete mappings unless the POS item should no longer be processed.
</Warning>
