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 POS mappings tell Bestellfix what should happen when a POS item is sold.
A POS item can be mapped to:
Mappings are used by integrations such as:
Lightspeed K-Series
Sides POS
CSV Upload
Screenshot Add screenshot here. What POS mapping does When a POS transfer runs, Bestellfix reads the sold POS items and checks whether each item has a mapping.
If a mapping exists, Bestellfix creates inventory movements.
Example:
POS item Mapping Inventory result Espresso Ingredient: Coffee beans Deduct coffee beans Cola 0.33l Ingredient: Cola bottle Deduct bottles Burger Recipe: Burger recipe Deduct all recipe ingredients
If no mapping exists, the item cannot be processed into inventory.
Mapping to an ingredient Use an ingredient mapping when one sold POS item should deduct one ingredient directly.
Example:
POS item Ingredient Quantity Cola 0.33l Cola bottle 1 Espresso Coffee beans 0.009 Wine glass 0.2l House wine 0.2
The quantity defines how much of the ingredient is deducted per sold POS item.
Screenshot Add screenshot here. Mapping to a recipe Use a recipe mapping when one sold POS item consists of multiple ingredients.
Example:
POS item Recipe Burger Burger recipe Pizza Margherita Pizza Margherita recipe Caesar Salad Caesar Salad recipe
When the POS item is sold, Bestellfix explodes the recipe and deducts all ingredients from the recipe lines.
This also supports sub-recipes.
Quantity multiplier The quantity field is a multiplier.
For ingredient mappings, it means:
sold quantity × mapping quantity = ingredient deduction
Example:
Sold Mapping quantity Deduction 3 × Cola 1 bottle 3 bottles 5 × Espresso 0.009 kg 0.045 kg
For recipe mappings, it means how many recipe portions are used per sold POS item.
Example:
Sold Mapping quantity Recipe portions 2 × Burger 1 2 portions 1 × Party platter 4 4 portions
Subtraction mappings Some mappings can use is_subtraction.
This is mainly useful for correction or reversal logic.
Example:
POS item Use case 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.
Lightspeed item mappings Lightspeed items are synced from Lightspeed K-Series.
To map a Lightspeed item:
Open Integrations
Select Lightspeed K-Series
Open the item list
Select a Lightspeed item
Choose ingredient or recipe
Enter the quantity
Save the mapping
Bestellfix stores the mapping by Lightspeed item name.
Screenshot Add screenshot here. Sides product mappings Sides products are synced from the Sides product API.
To map a Sides product:
Open Integrations
Select Sides POS
Open the product list
Select a Sides product
Choose ingredient or recipe
Enter the quantity
Save the mapping
Sides mappings are stored at integration level, not per store.
That means one product mapping can be used across stores of the same integration.
Screenshot Add screenshot here. CSV Upload mappings CSV Upload uses POS mappings based on POS item names or codes extracted from the uploaded CSV file.
The CSV integration reads configured columns and creates POS item codes from them.
These codes are then matched against POS mappings.
Example:
CSV value POS mapping BurgerBurger recipe Cola_033Cola bottle EspressoCoffee beans
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 can come from:
The linked Lightspeed location
The linked Sides store
Recipe or 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.
Recipe processing When a POS item is mapped to a recipe, Bestellfix calculates the required ingredient quantities from the recipe lines.
The recipe logic considers:
Quantity per portion
Portion multiplier
Trim percentage
Sub-recipes
Ingredient storage rules
If a recipe contains another recipe, Bestellfix expands the sub-recipe as well.
Preventing recipe cycles Recipes should not reference themselves directly or indirectly.
Example of a bad setup:
Burger recipe → Sauce recipe → Burger recipe
This creates a recipe cycle and cannot be processed correctly.
Common mapping errors Error Meaning recipe_not_foundThe selected recipe does not exist ingredient_not_foundThe selected ingredient does not exist pos_mapping_id_requiredA mapping ID is required for update or delete validation_errorRequired mapping data is missing or invalid unauthorized_accessThe mapping does not belong to the current user unmapped_pos_itemA POS item was sold but no mapping exists unmapped_pos_codeA CSV POS code was found but no mapping exists recipe_cycleA recipe references itself through recipe lines no_issue_storageNo storage unit could be resolved negative_stockThe 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
Updating mappings Mappings can be changed at any time.
After changing mappings, you may need to reprocess historical data.
For Lightspeed:
Use Manual Transfer for one date
Use Re-run Migration for a wider historical period
For Sides:
Use Manual Transfer for one date
Use Re-run Migration if historical billpositions should be processed again
Deleting mappings Deleting a mapping means future transfers can no longer process that POS item.
Existing inventory ledger entries are not automatically deleted just because a mapping is removed.
To correct previous postings, re-run the affected transfer or create correcting inventory movements.
Recommended setup order
Create ingredients
Create recipes
Connect the POS integration
Sync stores, locations, or items
Link storage units
Map the most important POS items
Run one manual transfer
Check the inventory ledger
Fix missing mappings
Activate automatic processing
Endpoint overview Action Endpoint List generic POS mappings GET /api/companies/<company_id>/pos-integrations/<integration_id>/mappings/Create generic POS mapping POST /api/companies/<company_id>/pos-integrations/<integration_id>/mappings/Map Lightspeed item POST /api/lightspeed/items/<id>/map/Delete Lightspeed item mapping DELETE /api/lightspeed/items/<id>/map/Map Sides product POST /api/sides/products/<product_id>/map/Update Sides product mapping PUT /api/sides/products/<product_id>/map/Delete Sides product mapping DELETE /api/sides/products/<product_id>/map/
Related pages
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.
