Skip to main content

​
Lightspeed K-Series

Use the Lightspeed K-Series integration to connect your Lightspeed POS with Mathership. The integration imports Lightspeed locations and POS items, lets you map POS items to ingredients or recipes, and creates inventory ledger entries from POS sales.

Connect Lightspeed

Connect Lightspeed through OAuth and securely store access and refresh tokens.

Map POS items

Map Lightspeed items to Mathership ingredients or recipes.

Create ledger entries

Transfer POS sales into inventory issue movements in the ledger.

​
What the integration can do

The integration can:
  • Connect Lightspeed through OAuth
  • Store Lightspeed access and refresh tokens securely
  • Refresh Lightspeed tokens automatically
  • Reauthorize an existing connection when needed
  • Sync Lightspeed business locations
  • Sync Lightspeed POS items
  • Link Lightspeed locations to Mathership 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
  • Keep transfer logs for review and troubleshooting

​
What the integration does

When a Lightspeed transfer runs, Mathership:
  1. Fetches Lightspeed sales for one location and one date
  2. Stores the raw Lightspeed sales and sales lines
  3. Reads the sold POS item names and quantities
  4. Finds matching POS mappings in Mathership
  5. Deducts mapped ingredients directly
  6. Expands mapped recipes into recipe ingredients
  7. Calculates inventory quantities
  8. Creates inventory ledger entries
  9. Links created ledger entries back to the Lightspeed sales lines
  10. Stores a transfer log with statistics, errors, skipped lines, and unmapped items

​
What the integration does not do

The Lightspeed integration does not:
  • Create ingredients automatically
  • Create recipes automatically
  • Guess item mappings automatically
  • Deduct inventory for unmapped items
  • Optimize stock levels
  • Change Lightspeed sales data
  • Push inventory back to Lightspeed
  • Create purchase orders
  • Calculate delivery routes
Lightspeed sales only affect inventory after the related Lightspeed items have been mapped to ingredients or recipes.
Use this order for a clean Lightspeed setup:
1

Create storage units

Set up the Mathership storage units that should receive inventory deductions.
2

Create ingredients

Make sure the ingredients used for POS item and recipe deductions exist.
3

Create recipes

Create recipes for POS items that should deduct multiple ingredients.
4

Connect Lightspeed

Authorize the Lightspeed K-Series connection through OAuth.
5

Sync locations

Import Lightspeed business locations into Mathership.
6

Link locations to storage units

Assign each Lightspeed location to the correct Mathership storage unit.
7

Sync items

Import Lightspeed POS items.
8

Map important items first

Start with high-volume items and items that strongly affect inventory.
9

Activate the location

Activate the location once storage units and mappings are ready.
10

Check migration status

Review the 90-day migration after activation.
11

Run a manual transfer

Test one date manually before relying on automatic transfer.
12

Check the ledger

Review created ledger entries and correct mappings if needed.
The most important setup rule is: locations need storage units, and Lightspeed items need mappings. Without both, sales cannot reliably create inventory movements.

​
Before you start

Before connecting Lightspeed, prepare these Mathership inventory objects.

​
Storage units

Each Lightspeed location must be linked to one Mathership storage unit. The storage unit defines where inventory should be deducted.

​
Ingredients

Ingredients are the inventory objects that are deducted.

​
Recipes

Recipes are used when one sold POS item consists of several ingredients. When the Lightspeed item is sold, Mathership deducts the ingredients inside the recipe.

​
Connect Lightspeed

Mathership stores access and refresh tokens securely. Tokens are refreshed automatically when they expire.

​
Required connection data

When the integration is created, Mathership needs:

​
What happens during connection

During connection, Mathership:
  1. Receives the OAuth authorization code
  2. Sends the code to the Lightspeed token endpoint
  3. Receives an access token and refresh token
  4. Encrypts the tokens before storing them
  5. Creates the integration and marks it as active

​
Token handling

Token lifetimes are read from the Lightspeed token response. They are not hardcoded.

​
Connection errors

​
Common connection problems

Mathership allows one Lightspeed integration per company.Use the existing integration or reauthorize it instead of creating another one.
Start the Lightspeed authorization flow again and submit a fresh authorization code.
This requires an administrator to check the Lightspeed OAuth configuration.

​
Reauthorize Lightspeed

Use reauthorization when an existing Lightspeed connection needs fresh authorization without losing your setup. This is needed when:
  • The refresh token expired
  • Lightspeed invalidated the token
  • Token refresh failed repeatedly
  • The integration status changed to disconnected
Reauthorization preserves:
  • Synced locations and storage-unit links
  • Synced items and item mappings
  • Transfer history and migration history
  • Existing logs

​
Token refresh behavior

If a Lightspeed API call returns 401, Mathership attempts to refresh the token automatically and retries the request once.

​
Sync locations

The location sync fetches business locations from Lightspeed and flattens them into a Mathership location list.

​
Location list columns

Filter the list by activated status, auto issue status, or storage unit using the toolbar.

​
Stored location data

​
Locations that disappear from Lightspeed

If a location no longer appears in the Lightspeed API, Mathership does not automatically delete it during sync. This avoids accidental loss of:
  • Storage-unit links
  • Mapping context
  • Transfer history
  • Migration history

​
Common location sync problems

Re-sync locations, check that the authorization is still valid, reauthorize if needed, and check Lightspeed account permissions.
Run location sync again. Mathership updates stored location data from the latest Lightspeed response.
Each Lightspeed location must be linked to a Mathership storage unit before transfers can deduct inventory. The same sold item can deduct inventory from different storage units depending on the location. You can remove a storage-unit link at any time. If a location is unbound during a migration, the migration can be cancelled. You can remove the storage-unit link again. Do this only if the location should no longer deduct inventory from that storage unit. If a location is unbound during a migration, the migration can be cancelled.

​
Storage-unit errors

Only link storage units that belong to the same company as the Lightspeed integration.

​
Sync items

Mathership fetches items for every synced Lightspeed location and deduplicates them by Lightspeed item ID across locations.

​
Item list columns

Filter the item list by mapped status, active status, or location using the toolbar chips.

​
Stored item data

Mathership tries to read the price from common Lightspeed price fields including prices.amount, prices.value, prices.price, price, and costPrice. If no usable price is found, the item is stored without a price.

​
Item states

​
Common item sync problems

Re-sync items, check whether locations were synced first, check Lightspeed account permissions, and reauthorize the integration if needed.
Run item sync again. Review mappings after major item-name changes, as mapping depends on the POS item name.
POS mappings are matched by POS item name. If Lightspeed item names change, existing mappings may no longer match transferred sales lines.

​
Map Lightspeed items

Click any item row to open the mapping sheet. Each Lightspeed item must be mapped before it can create inventory movements. You can map an item to:
  • An ingredient — the ingredient is deducted directly per sale
  • A recipe — the recipe is expanded into its ingredients and all lines are deducted

​
Why mapping is required

Without a mapping, Mathership can store the sale but cannot create the correct inventory deduction.

​
Mapping examples

When a recipe is sold, Mathership reads all recipe lines, applies trim percentages, expands any nested child recipes, and creates one ledger entry per ingredient.

​
Mapping quantity

The mapping quantity controls how much inventory is deducted per sold POS item.

​
Mapping fields

​
Subtraction mapping

Use is_subtraction carefully for special cases such as reversal logic, negative sales, or corrections.
Review subtraction mappings carefully. Incorrect subtraction logic can create inventory movements in the wrong direction.

​
Update or delete a mapping

To update a mapping, open the item, select a new ingredient or recipe, adjust the quantity, and save. Mathership replaces the existing mapping. To delete a mapping, open the item, remove the mapping, and save. The item will no longer create inventory deductions.

​
Mapping errors

​
Activate a location

A Lightspeed location must be activated before migration and regular transfer processing can run. Before activation, make sure:
  • The location has a storage unit
  • Important Lightspeed items are mapped
  • Recipes and ingredients are set up correctly
  • You understand which storage unit will receive the deductions

​
Location detail page

Opening a location shows a live overview of its health, activity, and configuration.

​
Health indicators

If any of the following are detected, a warning banner appears at the top of the page:
  • No storage unit linked
  • Recent transfers have failed
  • Recent transfers contain unmapped items
  • A migration is currently in progress

​
Stats

​
Configuration

​
90-day migration

When a location is activated, Mathership creates a 90-day historical migration that processes past Lightspeed sales and creates inventory movements where mappings exist.

​
Migration date range

The default migration range is the last 90 completed days, ending yesterday. If a successful transfer log already exists for a date, that day is marked as skipped in the initial migration.

​
Migration job creation

When a migration job is created, Mathership creates one day status for each date in the 90-day range. Each day can have its own status. If a successful transfer log already exists for a date, that day can be marked as skipped for the initial migration.

​
Migration job statuses

​
Migration day statuses

​
Migration progress fields

​
Migration actions

​
Recover stuck migrations

Mathership can reset stuck migration jobs. A running job is considered stuck if it has been running for too long. When recovered, the job is moved back to pending so processing can continue.

​
Retry failed migration days

Mathership can retry failed migration days automatically. Retries are limited by attempt count. If all failed days later succeed, the migration job is marked as completed. Re-run migration is useful when:
  • Many items were unmapped during the first migration
  • Ingredient or recipe mappings were corrected
  • Storage or recipe setup was fixed
  • Failed days need to be processed again
Mathership can also reset stuck migrations. A running job considered stuck for too long can be moved back to pending so processing can continue.

​
Migration errors

​
Automatic transfer

Once a location is activated, Mathership processes Lightspeed sales automatically each day. Toggle Auto issue in the Configuration section to pause or resume it. Pause automatic transfer when:
  • Mappings are incomplete or being corrected
  • A storage-unit link is wrong
  • You are investigating unexpected inventory movements
  • Lightspeed authorization needs to be repaired
  • You want to prevent automatic deductions temporarily
Pausing automatic transfer does not delete the integration, locations, mappings, or transfer history.

​
Manual transfer

Use manual transfer when you want to process one specific day. Manual transfer is useful for:
  • Testing the integration before enabling automatic transfer
  • Reprocessing a day after mapping changes
  • Fixing inventory after a failed transfer
  • Checking a specific Lightspeed sales date

​
Force refresh behavior

Manual transfers fetch fresh data from Lightspeed by default. When force refresh is active, Mathership:
  1. Fetches fresh sales data from Lightspeed
  2. Updates the cached Lightspeed sales and sales lines
  3. Deletes existing ledger entries for the same Lightspeed sales lines and current storage unit
  4. Recreates inventory ledger entries from the latest data
If sales are already cached and force refresh is not active, Mathership reuses cached data. Lines already posted to the current storage unit are skipped to avoid duplicate inventory deductions.

​
Idempotency

Lightspeed transfers are designed to avoid duplicate ledger entries. Mathership links created inventory ledger entries to Lightspeed sales lines. On later runs, already-posted sales lines are skipped for the current storage unit unless force_refresh is used.

​
What happens during transfer

When a Lightspeed transfer runs, Mathership:
  1. Checks that the location has a storage unit
  2. Creates a transfer log
  3. Fetches or reuses Lightspeed sales for the selected date
  4. Stores Lightspeed sales and sales lines
  5. Reads sold item names and quantities
  6. Skips lines already posted to the current storage unit
  7. Matches sold item names to POS mappings
  8. Deducts mapped ingredients directly
  9. Expands mapped recipes into ingredients
  10. Calculates weighted average cost
  11. Creates inventory ledger entries
  12. Links ledger entries to Lightspeed sales lines
  13. Updates the POS integration last run time
  14. Saves transfer statistics and errors

​
Sales date window

Mathership requests Lightspeed sales for the selected report date using a full-day UTC window.
The location timezone is stored, but the current transfer window uses a UTC day window.

​
Sales line processing

Only positive sales lines with a name are processed. A sales line is skipped when:
  • Quantity is missing, zero, or negative
  • Item name is missing
  • The line was already posted
  • The item is unmapped
  • The mapped ingredient or recipe cannot be resolved

​
POS mapping match

The transfer matches Lightspeed sales lines to POS mappings by POS item name. The Lightspeed sales line name must exactly match the mapped POS item name.
If item names in Lightspeed change, mappings may need to be reviewed or recreated.

​
Transfer result

A manual transfer returns a summary with the following information:

​
Transfer statistics

​
No data result

If Lightspeed has no data for the selected date, the transfer returns 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 for that day

​
Transfer errors

​
Retry behavior

For temporary Lightspeed API errors, Mathership retries the transfer automatically with the following delay sequence: Retryable cases include Lightspeed API server errors and HTTP 429 rate limit responses.

​
Processing logic

​
Ingredient mapping

If the mapping points to an ingredient, Mathership deducts that ingredient directly.

​
Recipe mapping

If the mapping points to a recipe, Mathership explodes the recipe and deducts all recipe ingredients. Recipes can contain child recipes. If a mapped recipe contains a child recipe, Mathership expands the child recipe as part of the transfer. Recipe lines can include a trim percentage. If trim percentage is configured, Mathership adjusts the required ingredient quantity. If trim percentage is invalid, the transfer records an invalid_trim_pct exception. If recipes reference each other in a cycle, Mathership stops the recursive expansion and records a recipe_cycle exception.

​
Unmapped items

If a sold Lightspeed item has no mapping, Mathership records the item name as unmapped and does not create any inventory deduction. Example exception: unmapped_pos_name:Espresso

​
Weighted average cost

Mathership calculates unit cost from receipt ledger entries using: total receipt value / total receipt quantity If no receipt quantity is available, the unit cost is 0.

​
Inventory ledger entries

Lightspeed transfers create inventory ledger entries of type ISSUE. Each entry is linked to:
  • Company and ingredient
  • Storage unit
  • Quantity deducted
  • Unit cost and total value
  • Date
  • Lightspeed location
  • Transfer log
  • Lightspeed sales line
See Ledger for detailed inventory history.

​
Transfer logs

Each transfer attempt creates a transfer log. Open logs from the See all logs button on the location detail page. The location detail page also shows the last 10 failed transfers directly, including the report date, attempt number, start time, and error message.

​
Integration alerts

Mathership raises integration alerts for Lightspeed failures. Alerts are deduplicated — repeated failures update the existing open alert instead of creating duplicates. When the integration recovers, open alerts are resolved automatically.

​
Testing checklist

Before relying on automatic transfers, test one day manually and 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
  • Unmapped item names are expected
  • Transfer log status is successful
  • No unexpected exceptions appear

​
Suggested test process

1

Choose a sales date

Choose a recent Lightspeed sales date with known sales.
2

Check location setup

Make sure the selected location has the correct storage unit.
3

Map important items

Map a small number of important POS items first.
4

Run a manual transfer

Run a manual transfer with force refresh.
5

Review the result

Check created ledger IDs, unmapped names, and transfer statistics.
6

Check the ledger

Confirm ingredient quantities and storage unit in the ledger.
7

Correct mappings if needed

Fix missing or incorrect mappings.
8

Run the transfer again

Confirm that corrected items now create ledger entries.

​
Best practices

Set up inventory first

Create storage units, ingredients, and recipes before relying on Lightspeed transfers.

Start with one location

Connect and test one Lightspeed location first. After it works, continue with additional locations.

Map high-volume items first

Start with the items sold most often. This creates the biggest inventory benefit quickly.

Test manually first

Always test one day manually before enabling automatic transfer.

Review unmapped items

Unmapped items are expected during setup. Use them as a working list for missing mappings.

Keep item names stable

Mapping depends on POS item names. If Lightspeed item names change, review mappings.

Use reauthorization

If authorization fails, reauthorize the existing integration. Deleting removes setup data.

Check ledger results

After transfers, check the ledger to confirm quantities, storage units, and ingredients.

​
Common problems

Use the existing integration or reauthorize it instead of creating a second one.
Start the Lightspeed authorization flow again and submit a fresh authorization code.
Lightspeed rejected the refresh token.Open the integration, start reauthorization, authorize Mathership in Lightspeed again, and confirm the integration status becomes active.
Re-sync locations, check the Lightspeed authorization, reauthorize if needed, and check Lightspeed account permissions.
Re-sync items, check whether locations were synced first, check Lightspeed permissions, and reauthorize if authorization may have expired.
Check that a storage unit is linked and saved, and that at least one item is mapped.
Check that the location is activated, has a linked storage unit, and that no other migration is already pending or running.
Check the selected date, whether Lightspeed has sales for that date with positive quantities, whether items are mapped, whether item names match POS mappings, whether recipes contain ingredients, whether the location has a storage unit, and whether the lines were already posted.
Open the transfer result, review unmapped_names, create or correct mappings, check recipe ingredients, re-run the manual transfer with force refresh, and re-run migration if historical data should be corrected.
  1. Pause automatic transfer
  2. Correct the storage-unit link and save
  3. Review existing ledger entries for the affected dates
  4. Decide whether affected days should be reversed or reprocessed
  5. Run manual transfer carefully after correction
Check that the sales line name exactly matches the mapped POS item name, the mapped ingredient or recipe still exists, the recipe contains ingredient lines, the sold quantity is greater than zero, and the transfer was run after the mapping was created.
Check the date, the Lightspeed location, whether the selected day has closed sales, and whether Lightspeed returned report data for that day.

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.

Ledger

Review inventory movements created by Lightspeed transfers.
Last modified on June 7, 2026