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.

Map ingredients

Deduct one ingredient directly when a simple POS item is sold.

Map recipes

Expand a sold POS item into recipe ingredients and deduct them from inventory.

Review unmapped items

Use unmapped POS items as a working list for missing mappings.

Map ingredients

Deduct one ingredient directly when a simple POS item is sold.

Map recipes

Expand a sold POS item into recipe ingredients and deduct them from inventory.

Review unmapped items

Use unmapped POS items as a working list for missing mappings.

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

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.

Ingredient quantity
Recipe 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

Sold	Mapping quantity	Recipe portions
2 × Burger	1	2 portions
1 × Party platter	4	4 portions
3 × Small salad	0.5	1.5 portions

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.

Review subtraction mappings carefully. Incorrect subtraction logic can create inventory movements in the wrong direction.

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.

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

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:

Burger recipe → Burger bun → Beef patty → Sauce recipe → Mayonnaise, Ketchup, Spices

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.

Bad example: Burger recipe → Sauce recipe → Burger recipe

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

Ingredient quantity
Recipe 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

Sold	Mapping quantity	Recipe portions
2 × Burger	1	2 portions
1 × Party platter	4	4 portions
3 × Small salad	0.5	1.5 portions

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

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.

Review subtraction mappings carefully. Incorrect subtraction logic can create inventory movements in the wrong direction.

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

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

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:

Burger recipe → Burger bun → Beef patty → Sauce recipe → Mayonnaise, Ketchup, Spices

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.

Bad example: Burger recipe → Sauce recipe → Burger recipe

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.

Lightspeed
SIDES

Use Manual Transfer for one date
Use Re-run Migration for a wider historical period

Testing a mapping

To test a mapping:

Choose a POS item

Choose one POS item with known sales.

Confirm the mapping exists

Confirm that the POS item is mapped.

Check the target

Confirm that the mapped ingredient or recipe is correct.

Check the quantity factor

Confirm that the quantity factor is correct.

Run a manual transfer

Run a manual transfer for one date.

Open the inventory ledger

Review the created inventory movement.

Compare the result

Compare the deducted quantity with the expected quantity.

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

Start with top sellers

Start with the most frequently sold POS items.

Use recipes for dishes

Use recipes for prepared dishes, drinks, menus, and items with multiple ingredients.

Use ingredients for simple items

Use direct ingredient mappings for simple packaged items.

Keep POS names stable

POS item name changes can break mappings.

Check quantities carefully

Wrong quantity factors make inventory deductions too high or too low.

Test before automation

Test one date manually before enabling automation.

Review unmapped items

Review unmapped items after the first transfer.

Check the ledger

Check the inventory ledger after every major mapping change.

Do not delete mappings unless the POS item should no longer be processed.

Lightspeed K-Series

Connect Lightspeed and process POS sales.

Sides POS

Connect Sides POS and sync stores and products.

CSV Upload

Upload POS sales data from CSV files.

Inventory Ledger

Review inventory movements created from POS transfers.

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.

Lightspeed
SIDES

Use Manual Transfer for one date
Use Re-run Migration for a wider historical period

Testing a mapping

Choose a POS item

Choose one POS item with known sales.

Confirm the mapping exists

Confirm that the POS item is mapped.

Check the target

Confirm that the mapped ingredient or recipe is correct.

Check the quantity factor

Confirm that the quantity factor is correct.

Run a manual transfer

Run a manual transfer for one date.

Open the inventory ledger

Review the created inventory movement.

Compare the result

Compare the deducted quantity with the expected quantity.

Start with top sellers

Start with the most frequently sold POS items.

Use recipes for dishes

Use recipes for prepared dishes, drinks, menus, and items with multiple ingredients.

Use ingredients for simple items

Use direct ingredient mappings for simple packaged items.

Keep POS names stable

POS item name changes can break mappings.

Check quantities carefully

Wrong quantity factors make inventory deductions too high or too low.

Test before automation

Test one date manually before enabling automation.

Review unmapped items

Review unmapped items after the first transfer.

Check the ledger

Check the inventory ledger after every major mapping change.

Do not delete mappings unless the POS item should no longer be processed.

​POS Mapping

Map ingredients

Map recipes

Review unmapped items

Map ingredients

Map recipes

Review unmapped items

​What POS mapping does

​Why mappings are required

​Mapping types

​Mapping to an ingredient

​Mapping to a recipe

​Why mappings are required

​Mapping types

​Mapping to an ingredient

​Mapping to a recipe

​Quantity multiplier

​Subtraction mappings

​Where to create mappings

​The mapping sheet

​Mapping form fields

​Lightspeed item mappings

​SIDES product mappings

​Editing a mapping

​Deleting a mapping

​Mapping state in the item list

​Storage unit selection

​Recipe processing

​Trim percentage

​Preventing recipe cycles

​Unmapped POS items

​Common mapping errors

​Mapping checklist

​Good mapping examples

​Quantity multiplier

​Subtraction mappings

​Where to create mappings

​The mapping sheet

​Mapping form fields

​Lightspeed item mappings

​SIDES product mappings

​Editing a mapping

​Deleting a mapping

​Mapping state in the item list

​Storage unit selection

​Recipe processing

​Trim percentage

​Preventing recipe cycles

​Unmapped POS items

​Common mapping errors

​Mapping checklist

​Good mapping examples

​Poor mapping examples

​Updating mappings

​Testing a mapping

​Best practices

Start with top sellers

Use recipes for dishes

Use ingredients for simple items

Keep POS names stable

Check quantities carefully

Test before automation

Review unmapped items

Check the ledger

​Related pages

Lightspeed K-Series

Sides POS

CSV Upload

Inventory Ledger

​Poor mapping examples

​Updating mappings

​Testing a mapping

Start with top sellers

Use recipes for dishes

Use ingredients for simple items

Keep POS names stable

Check quantities carefully

Test before automation

Review unmapped items

Check the ledger

POS Mapping

What POS mapping does

Why mappings are required

Mapping types

Mapping to an ingredient

Mapping to a recipe

Why mappings are required

Mapping types

Mapping to an ingredient

Mapping to a recipe

Quantity multiplier

Subtraction mappings

Where to create mappings

The mapping sheet

Mapping form fields

Lightspeed item mappings

SIDES product mappings

Editing a mapping

Deleting a mapping

Mapping state in the item list

Storage unit selection

Recipe processing

Trim percentage

Preventing recipe cycles

Unmapped POS items

Common mapping errors

Mapping checklist

Good mapping examples

Quantity multiplier

Subtraction mappings

Where to create mappings

The mapping sheet

Mapping form fields

Lightspeed item mappings

SIDES product mappings

Editing a mapping

Deleting a mapping

Mapping state in the item list

Storage unit selection

Recipe processing

Trim percentage

Preventing recipe cycles

Unmapped POS items

Common mapping errors

Mapping checklist

Good mapping examples

Poor mapping examples

Updating mappings

Testing a mapping

Best practices

Related pages

Poor mapping examples

Updating mappings

Testing a mapping