​

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.

​

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

​

Recommended setup order

Use this order for a clean Lightspeed setup:

​

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

​

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

​

Link a storage unit

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.

​

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. If a location is unbound during a migration, the migration can be cancelled.

​

Storage-unit errors

​

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

​

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.

​

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

​

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.

​

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.

​

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

​

Best practices

​

Common problems

​

Related pages