​

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.

​

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. 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. The POS item name alone is not enough. A mapping connects the external POS item to the correct Mathership inventory object.

​

Mapping types

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

​

Mapping to a recipe

Use a recipe mapping when one sold POS item consists of multiple ingredients. When the POS item is sold, Mathership expands the recipe and deducts all ingredients from the recipe lines. This also supports sub-recipes. 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. The POS item name alone is not enough. A mapping connects the external POS item to the correct Mathership inventory object.

​

Mapping types

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

​

Mapping to a recipe

Use a recipe mapping when one sold POS item consists of multiple ingredients. 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. 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. Only use this when the POS item should not behave like a normal sale deduction.

​

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.

​

Mapping form fields

​

Lightspeed item mappings

Lightspeed items are synced from Lightspeed K-Series. Mathership stores the mapping using the Lightspeed item name.

​

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.

​

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

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

​

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. 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. Only use this when the POS item should not behave like a normal sale deduction.

​

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.

​

Mapping form fields

​

Lightspeed item mappings

Lightspeed items are synced from Lightspeed K-Series. Mathership stores the mapping using the Lightspeed item name.

​

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.

​

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

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

​

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

​

Poor mapping examples

​

Updating mappings

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

​

Testing a mapping

To test a mapping:

​

Best practices

​

Related pages

​

Poor mapping examples

​

Updating mappings

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

​

Testing a mapping