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.
Lightspeed K-Series Use the Lightspeed K-Series integration to connect your Lightspeed POS with Bestellfix.
The integration can:
Connect Lightspeed through OAuth
Sync Lightspeed locations
Sync Lightspeed items
Link locations to storage units
Map Lightspeed items to ingredients or recipes
Run a 90-day historical migration
Run automatic daily transfers
Run manual one-day transfers
Create inventory ledger entries from POS sales
Overview The Lightspeed integration follows this setup flow:
Connect Lightspeed
Sync locations
Link each location to a storage unit
Sync items
Map Lightspeed items to ingredients or recipes
Activate the location
Review the 90-day migration
Use automatic or manual transfers
Screenshot Add screenshot here. Connect Lightspeed To connect Lightspeed:
Open Manage → Integrations
Select Lightspeed K-Series
Start the Lightspeed connection flow
Authorize Bestellfix in Lightspeed
Return to Bestellfix
Save the integration
Bestellfix receives an OAuth authorization code from the frontend and exchanges it for Lightspeed tokens.
The tokens are stored securely and used for future syncs and transfers.
Required connection data When the integration is created, Bestellfix needs:
Field Meaning company_idThe company that owns the integration nameInternal name for the integration codeOAuth authorization code from Lightspeed
Possible connection errors Error Meaning lightspeed_integration_existsA Lightspeed integration already exists lightspeed_oauth_exchange_failedThe authorization code could not be exchanged lightspeed_not_configuredLightspeed OAuth is not configured correctly unauthorized_company_accessThe company does not belong to the current user
Reauthorize Lightspeed Use reauthorization when the Lightspeed connection needs fresh authorization.
This keeps the existing setup in place.
Reauthorization preserves:
Locations
Storage-unit links
Item mappings
Transfer history
Migration history
To reauthorize:
Open the existing Lightspeed integration
Start the Lightspeed authorization flow again
Submit the new authorization code
Bestellfix replaces the stored tokens
Screenshot Add screenshot here. Sync locations After connecting Lightspeed, sync locations.
Locations represent Lightspeed business locations or sales locations.
To sync locations:
Open the Lightspeed integration
Click Sync Locations
Wait until the locations are loaded
Review the location list
The location sync fetches locations from Lightspeed and stores them in Bestellfix.
Location list The location list shows cached Lightspeed locations.
Each location can be linked to a Bestellfix storage unit.
Typical fields are:
Field Meaning Location name Name from Lightspeed Storage unit Linked Bestellfix storage unit Activated Whether transfers are active Auto transfer paused Whether automatic transfer is paused
Screenshot Add screenshot here. Link a storage unit Each Lightspeed location must be linked to a Bestellfix storage unit before it can be activated.
The storage unit tells Bestellfix where inventory should be deducted.
To link a storage unit:
Open the Lightspeed location
Choose a storage unit
Save the link
A location cannot be activated without a storage unit.
Unlink a storage unit You can remove the storage-unit link again.
Do this only if the location should no longer deduct inventory from that storage unit.
Common storage-unit errors Error Meaning storage_unit_requiredA storage unit must be linked before activation or transfer storage_unit_company_mismatchThe selected storage unit belongs to another company
Sync items After syncing locations, sync Lightspeed items.
Items are the products or sales items from Lightspeed.
To sync items:
Open the Lightspeed integration
Click Sync Items
Wait until the items are loaded
Review the item list
Bestellfix stores the synced items and shows whether each item is mapped.
Item list The item list is ordered by name and can show mapping information.
Typical item states:
State Meaning Unmapped The item has no inventory mapping yet Mapped to ingredient The item deducts one ingredient directly Mapped to recipe The item deducts recipe ingredients Subtraction mapping The item can reverse or subtract depending on setup
Screenshot Add screenshot here. Map Lightspeed items Each Lightspeed item must be mapped before it can create inventory movements.
You can map an item to:
Map to an ingredient Use ingredient mapping when the Lightspeed item should deduct one ingredient directly.
Example:
Lightspeed item Mapped to Quantity Cola 0.33l Cola bottle 1 Espresso Coffee beans 0.009
Map to a recipe Use recipe mapping when the Lightspeed item consists of multiple ingredients.
Example:
Lightspeed item Mapped to Classic Burger Classic Burger recipe Pizza Margherita Pizza Margherita recipe
When the item is sold, Bestellfix explodes the recipe and deducts the recipe ingredients.
Mapping fields Field Meaning mapped_object_typeingredient or recipemapped_object_idID of the ingredient or recipe quantityMultiplier used for the mapped object is_subtractionWhether the mapping is treated as subtraction/reversal logic
Update a mapping To change a mapping:
Open the Lightspeed item
Select a new ingredient or recipe
Adjust the quantity if needed
Save the mapping
Bestellfix replaces the existing mapping for that item.
Delete a mapping To delete a mapping:
Open the Lightspeed item
Remove the mapping
Save
After deleting a mapping, the item will no longer create inventory deductions.
Mapping errors Error Meaning recipe_not_foundThe selected recipe does not exist for this company ingredient_not_foundThe selected ingredient does not exist for this company unauthorized_company_accessThe item or integration does not belong to the current user
Activate a location A Lightspeed location must be activated before migration and transfers can run.
Before activation, make sure:
The location has a storage unit
Important Lightspeed items are mapped
Recipes and ingredients are set up correctly
To activate a location:
Open the Lightspeed location
Check the linked storage unit
Click Activate
Bestellfix starts a 90-day migration
Activation sets the location to active and starts the historical migration if no migration is already running.
Screenshot Add screenshot here. 90-day migration When a location is activated, Bestellfix creates a 90-day historical migration.
The migration processes past Lightspeed sales and creates inventory movements where mappings exist.
The migration is useful because it can backfill inventory usage from recent POS sales.
Migration status You can poll the migration status from the location.
Typical migration states are:
State Meaning Pending Migration has been created but not started Running Migration is currently processing Completed Migration finished Cancelled Migration was cancelled Failed Migration stopped because of an error
Re-run migration Use Re-run Migration if you added or corrected mappings after activation.
A re-run processes the historical period again.
Bestellfix prevents starting another migration while one is already pending or running.
Cancel migration Use Cancel Migration if a migration should stop.
Cancellation applies to pending or running migration jobs for the location.
Migration errors Error Meaning location_not_activatedThe location must be activated first storage_unit_requiredThe location has no linked storage unit migration_already_in_progressA migration is already pending or running
Automatic transfer Lightspeed locations can use automatic transfer.
Automatic transfer is intended for regular daily processing.
You can pause or resume automatic transfer for each location.
Pause automatic transfer To pause automatic transfer:
Open the Lightspeed location
Click Toggle Auto Transfer
Confirm that automatic transfer is paused
When paused, the location remains connected but nightly transfer should not run.
Resume automatic transfer Click Toggle Auto Transfer again to resume automatic transfer.
The value switches between paused and active.
Screenshot Add screenshot here. Manual transfer Use manual transfer when you want to process one specific day.
Manual transfer is useful for:
Testing the integration
Reprocessing a day
Fixing inventory after mapping changes
Checking a specific Lightspeed sales date
Run a manual transfer To run a manual transfer:
Open the Lightspeed location
Open Manual Transfer
Enter the date
Start the transfer
Review the result
The date should use this format:
Example:
The backend also accepts this format:
Example:
Manual transfer refresh behavior Manual transfer can use force_refresh.
By default, force_refresh is treated as enabled.
That means Bestellfix fetches fresh Lightspeed data and recreates the relevant inventory entries for that location and date.
What happens during transfer When a Lightspeed transfer runs, Bestellfix:
Fetches Lightspeed sales data for the location and date
Reads sold items
Matches sold items to POS mappings
Explodes recipe mappings into ingredients
Calculates ingredient quantities
Creates inventory ledger entries
Returns a transfer summary
Transfer result A manual transfer returns a summary.
The response can include:
Field Meaning dateProcessed report date successWhether the transfer succeeded no_dataWhether Lightspeed returned no sales data log_idTransfer log reference ledger_idsCreated inventory ledger entry IDs statsProcessing statistics errorError message if processing failed
No data result If Lightspeed has no data for the selected date, the transfer can return no_data.
This usually means:
No sales were found for that location and date
The wrong date was entered
The wrong location was selected
Lightspeed did not return report data
Transfer errors Error Meaning date_requiredNo date was provided invalid_date_formatThe date format is invalid storage_unit_requiredThe location has no linked storage unit lightspeed_auth_failedLightspeed authentication failed lightspeed_api_errorLightspeed API returned an error
Inventory ledger entries Lightspeed transfers create inventory ledger entries.
These entries reduce inventory based on sold POS items.
The ledger entries are connected to:
Company
Ingredient
Storage unit
Transaction type
Quantity
Unit cost
Value
Date
Transfer log or source data
See Inventory Ledger for detailed inventory history.
Processing logic The transfer uses the same inventory logic as other POS integrations.
Sold Lightspeed items are processed through POS mappings.
If the mapping points to an ingredient, Bestellfix deducts that ingredient directly.
If the mapping points to a recipe, Bestellfix explodes the recipe and deducts all recipe ingredients.
Example Lightspeed sale Mapping Inventory result 1 × Espresso Coffee beans Deduct coffee beans 2 × Cola 0.33l Cola bottle Deduct 2 bottles 1 × Burger Burger recipe Deduct all burger ingredients
Recommended setup order Use this order for a clean Lightspeed setup:
Create storage units
Create ingredients
Create recipes
Connect Lightspeed
Sync locations
Link locations to storage units
Sync items
Map important items first
Activate the location
Check migration status
Run a manual transfer for one test date
Check the inventory ledger
Enable automatic transfer
Testing checklist Before relying on automatic transfers, test one day manually.
Check that:
The correct Lightspeed location was used
The location has the correct storage unit
The correct date was processed
Sold items were found
Important items are mapped
Recipe ingredients were deducted correctly
Quantities are correct
Ledger entries appear in the correct storage unit
Screenshot Add screenshot here. Common problems Lightspeed connection already exists Bestellfix returns:
lightspeed_integration_exists
Use the existing integration or reauthorize it instead of creating a second one.
Authorization failed Bestellfix returns:
lightspeed_oauth_exchange_failed
Start the Lightspeed authorization flow again and submit a fresh authorization code.
Locations are missing Try:
Re-sync locations
Check the Lightspeed authorization
Reauthorize the integration if needed
Items are missing Try:
Re-sync items
Check whether locations were synced first
Check the Lightspeed account permissions
Location cannot be activated Usually this means no storage unit is linked.
Fix:
Open the location
Link a storage unit
Save
Activate again
Transfer creates no inventory entries Check:
The selected date
Whether Lightspeed has sales for that date
Whether items are mapped
Whether recipes contain ingredients
Whether storage units are configured
Some items are skipped Items can be skipped when they are unmapped or cannot be resolved into ingredients.
Fix the item mappings and re-run the manual transfer or migration.
Related pages
Integrations Overview Return to the integrations overview.
POS Mapping Map POS items to ingredients or recipes.
Storage Units Manage storage units used for Lightspeed deductions.
Inventory Ledger Review inventory movements created by Lightspeed transfers.
