> ## 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
> Connect Lightspeed K-Series with Mathership to transfer POS sales into inventory movements
# 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 through OAuth and securely store access and refresh tokens.
Map Lightspeed items to Mathership ingredients or recipes.
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.
## Recommended setup order
Use this order for a clean Lightspeed setup:
Set up the Mathership storage units that should receive inventory deductions.
Make sure the ingredients used for POS item and recipe deductions exist.
Create recipes for POS items that should deduct multiple ingredients.
Authorize the Lightspeed K-Series connection through OAuth.
Import Lightspeed business locations into Mathership.
Assign each Lightspeed location to the correct Mathership storage unit.
Import Lightspeed POS items.
Start with high-volume items and items that strongly affect inventory.
Activate the location once storage units and mappings are ready.
Review the 90-day migration after activation.
Test one date manually before relying on automatic transfer.
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.
| Required setup | Why it is needed |
| -------------- | ----------------------------------------------------------------- |
| Storage units | Inventory deductions need a target storage unit |
| Ingredients | POS items or recipe lines deduct ingredients |
| Recipes | Recipe-mapped POS items are exploded into ingredients |
| POS mappings | Lightspeed item names need to be linked to ingredients or recipes |
## Storage units
Each Lightspeed location must be linked to one Mathership storage unit.
The storage unit defines where inventory should be deducted.
| Lightspeed location | Mathership storage unit |
| ------------------- | ----------------------- |
| Restaurant Main POS | Main Kitchen |
| Bar POS | Bar Storage |
| Terrace POS | Terrace Storage |
## Ingredients
Ingredients are the inventory objects that are deducted.
| Ingredient | Unit |
| ------------------ | ------ |
| Coffee beans | kg |
| Cola bottle 0.33 l | bottle |
| Burger bun | piece |
| Tomato | kg |
## 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.
| Lightspeed item | Mathership recipe |
| ---------------- | ----------------------- |
| Classic Burger | Classic Burger recipe |
| Pizza Margherita | Pizza Margherita recipe |
| Espresso Martini | Espresso Martini 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:
| Field | Meaning |
| ------------ | ---------------------------------------- |
| `company_id` | The company that owns the integration |
| `name` | Internal name for the integration |
| `code` | OAuth authorization code from Lightspeed |
### 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 | Use |
| -------------------- | ----------------------------------- |
| Access token | Used for Lightspeed API calls |
| Refresh token | Used to receive a new access token |
| Access token expiry | Stored from the Lightspeed response |
| Refresh token expiry | Stored from the Lightspeed response |
Token lifetimes are read from the Lightspeed token response. They are not hardcoded.
### Connection errors
| Error | Meaning |
| ---------------------------------- | -------------------------------------------------------- |
| `lightspeed_integration_exists` | A Lightspeed integration already exists for this company |
| `lightspeed_oauth_exchange_failed` | The authorization code could not be exchanged |
| `lightspeed_not_configured` | Lightspeed OAuth is not configured correctly |
| `unauthorized_company_access` | The company does not belong to the current user |
### 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.
| Refresh outcome | Result |
| -------------------------- | -------------------------------------------------------------------- |
| Success | New tokens stored, integration stays active, open alerts resolved |
| Fails with `invalid_grant` | Integration marked as disconnected, reauthorization required |
| Fails with server error | Integration marked as refresh failed, alert raised, may be retryable |
## Sync locations
The location sync fetches business locations from Lightspeed and flattens them into a Mathership location list.
### Location list columns
| Column | Description |
| ------------ | ------------------------------------------------------ |
| Location ID | Lightspeed business location ID |
| Name | Location name with country and timezone |
| Storage unit | Linked Mathership storage unit, or **Unmapped** |
| Currency | Currency code from Lightspeed |
| Activated | Whether the location is activated for daily issues |
| Auto issue | Whether automatic daily processing is active or paused |
| Last synced | When the location was last synced |
Filter the list by activated status, auto issue status, or storage unit using the toolbar.
### Stored location data
| Field | Meaning |
| ---------------------- | --------------------------------- |
| `business_location_id` | Lightspeed business location ID |
| `name` | Lightspeed location name |
| `country` | Location country from Lightspeed |
| `timezone` | Location timezone from Lightspeed |
| `currency_code` | Currency code from Lightspeed |
| `last_synced_at` | Last location sync time |
### 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.
## 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.
| Lightspeed location | Storage unit | Result |
| ------------------- | --------------- | ---------------------------------- |
| Bar POS | Bar Storage | Drinks deducted from bar stock |
| Restaurant POS | Main Kitchen | Food deducted from kitchen stock |
| Terrace POS | Terrace Storage | Terrace sales deduct terrace stock |
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
| Error | Meaning |
| ------------------------------- | ------------------------------------------------------------ |
| `storage_unit_required` | A storage unit must be linked before activation or transfer |
| `storage_unit_company_mismatch` | The selected storage unit belongs to another company |
| `location_has_no_storage_unit` | Transfer cannot run because the location has no storage unit |
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
| Column | Description |
| --------- | ----------------------------------------------------------------------------- |
| Name | POS item name and Lightspeed item ID |
| SKU | SKU from Lightspeed, if available |
| Price | Item price synced from Lightspeed |
| Active | Whether the item is active in Lightspeed |
| Mapped | Whether the item has a Mathership mapping |
| Mapped to | The ingredient or recipe the item maps to, with quantity and subtraction flag |
| Locations | Which Lightspeed locations this item appears in |
Filter the item list by mapped status, active status, or location using the toolbar chips.
### Stored item data
| Field | Meaning |
| ---------------- | --------------------------------- |
| `item_id` | Lightspeed item ID |
| `name` | Lightspeed item name |
| `sku` | SKU from Lightspeed, if available |
| `active` | Whether the item is active |
| `price` | Item price, if available |
| `last_synced_at` | Last item sync time |
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
| State | Meaning |
| ---------- | --------------------------------------------- |
| Not mapped | The item has no inventory mapping yet |
| Mapped | The item is mapped to an ingredient or recipe |
### 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.
| Lightspeed sale | Required Mathership meaning |
| --------------- | ------------------------------------------- |
| Espresso | Deduct coffee beans |
| Cola 0.33 l | Deduct one Cola bottle |
| Classic Burger | Deduct all ingredients in the burger recipe |
### Mapping examples
| Lightspeed item | Mapped to | Mapping qty | Sale qty | Inventory effect |
| --------------- | ------------- | ----------- | -------- | -------------------- |
| Cola 0.33 l | Cola bottle | 1 | 2 | 2 bottles |
| Espresso | Coffee beans | 0.009 | 10 | 0.09 kg coffee beans |
| Burger | Burger recipe | 1 | 3 | 3 recipe portions |
| Lightspeed item | Mapped to | Sale qty | Result |
| ---------------- | ----------------------- | -------- | -------------------------- |
| Classic Burger | Classic Burger recipe | 5 | All burger ingredients × 5 |
| Pizza Margherita | Pizza Margherita recipe | 3 | All pizza ingredients × 3 |
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.
| Lightspeed item | Mapping target | Mapping quantity | Sale quantity | Inventory effect |
| --------------- | -------------- | ---------------: | ------------: | -------------------- |
| Cola 0.33 l | Cola bottle | 1 | 2 | 2 bottles |
| Espresso | Coffee beans | 0.009 | 10 | 0.09 kg coffee beans |
| Burger | Burger recipe | 1 | 3 | 3 recipe portions |
### Mapping fields
| Field | Meaning |
| -------------------- | --------------------------------------------------- |
| `mapped_object_type` | `ingredient` or `recipe` |
| `mapped_object_id` | ID of the ingredient or recipe |
| `quantity` | Multiplier used for the mapped object |
| `is_subtraction` | Whether the mapping uses reversal/subtraction logic |
### 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
| Error | Meaning |
| ----------------------------- | ----------------------------------------------------------- |
| `recipe_not_found` | The selected recipe does not exist for this company |
| `ingredient_not_found` | The selected ingredient does not exist for this company |
| `unauthorized_company_access` | The item or integration does not belong to the current user |
## 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
| Stat | Description |
| ----------------- | ----------------------------------------------------------------------------------- |
| Issues (lifetime) | Total issues ever processed with failure count |
| Issues (7d / 30d) | Issues processed in the last 7 and 30 days |
| Catalog mapped | How many Lightspeed items are mapped out of total — click to open the products page |
| Sales (7d / 30d) | Lightspeed sales lines seen in the last 7 and 30 days |
### Configuration
| Setting | Description |
| ----------------- | ---------------------------------------------------------------------------- |
| Storage unit | The storage unit where inventory is deducted — click **Save** after changing |
| Activate location | One-way toggle to activate the location for daily issues |
| Auto issue | Toggle to pause or resume automatic daily processing |
| Manual issue | Date picker to trigger a one-off issue for a specific past date |
## 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.
| Example | Date |
| ----------- | ---------- |
| If today is | 2026-05-08 |
| Start date | 2026-02-07 |
| End date | 2026-05-07 |
| Total days | 90 |
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
| Status | Meaning |
| ----------- | ---------------------------------------------- |
| `pending` | Migration has been created but not started |
| `running` | Migration is currently processing |
| `completed` | Migration finished successfully |
| `cancelled` | Migration was cancelled |
| `failed` | Migration finished but one or more days failed |
### Migration day statuses
| Status | Meaning |
| --------------- | ------------------------------------------------------------ |
| `pending` | Day is waiting to be processed |
| `processing` | Day is currently being processed |
| `success` | Day was processed successfully |
| `no_data` | Lightspeed returned no sales data for that day |
| `failed` | Day failed during processing |
| `retry_pending` | Failed day is waiting for retry |
| `skipped` | Day was skipped because a successful transfer already exists |
### Migration progress fields
| Field | Meaning |
| ------------------ | ------------------------------------------ |
| `total_days` | Number of days in the migration |
| `days_processed` | Days successfully processed |
| `days_failed` | Days that failed |
| `days_skipped` | Days skipped because prior success existed |
| `current_date` | Date currently being processed |
| `start_date` | First date in the migration |
| `end_date` | Last date in the migration |
| `progress_percent` | Migration progress percentage |
| `started_at` | Start timestamp |
| `completed_at` | Completion timestamp |
| `error_message` | Error message for failed or cancelled jobs |
### Migration actions
| Action | When to use |
| ---------------- | ----------------------------------------------------------------------- |
| Start migration | When no migration exists for the location |
| Re-run migration | After adding or correcting mappings — reprocesses the full 90-day range |
| Cancel migration | When you need to stop a pending or running migration |
### 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
| Error | Meaning |
| ------------------------------- | ----------------------------------------- |
| `location_not_activated` | The location must be activated first |
| `storage_unit_required` | The location has no linked storage unit |
| `migration_already_in_progress` | A migration is already pending or running |
## 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.
| State | Meaning |
| ------ | -------------------------------------------------- |
| Active | Daily Lightspeed sales are processed automatically |
| Paused | No automatic processing — manual issues still work |
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:
| Field | Meaning |
| ------------ | ----------------------------------------- |
| `date` | Processed report date |
| `success` | Whether the transfer succeeded |
| `no_data` | Whether Lightspeed returned no sales data |
| `log_id` | Transfer log reference |
| `ledger_ids` | Created inventory ledger entry IDs |
| `stats` | Processing statistics |
| `error` | Error message if processing failed |
### Transfer statistics
| Field | Meaning |
| ------------------------ | -------------------------------------------------------------------- |
| `sales_count` | Number of Lightspeed sales processed |
| `lines_processed` | Number of sales lines processed |
| `lines_skipped` | Number of sales lines skipped |
| `ledger_entries_created` | Number of inventory ledger entries created |
| `exceptions` | Mapping or recipe processing issues |
| `used_cache` | Whether cached sales were used |
| `idempotent` | Whether no new entries were needed because lines were already posted |
| `recipes_used` | Summary of mapped recipes or ingredients used |
| `unmapped_names` | POS item names without mappings |
| `api_response_summary` | Summary of fetched or cached Lightspeed data |
### 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
| Error | Meaning |
| ------------------------------ | --------------------------------------------- |
| `date_required` | No date was provided |
| `invalid_date_format` | The date format is invalid |
| `storage_unit_required` | The location has no linked storage unit |
| `location_has_no_storage_unit` | The selected location cannot deduct inventory |
| `lightspeed_auth_failed` | Lightspeed authentication failed |
| `lightspeed_api_error` | Lightspeed API returned an error |
| `max_retries_exhausted` | Transfer failed after all retry attempts |
### Retry behavior
For temporary Lightspeed API errors, Mathership retries the transfer automatically with the following delay sequence:
| Retry attempt | Delay |
| ------------- | ----------- |
| 1 | 30 seconds |
| 2 | 60 seconds |
| 3 | 120 seconds |
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.
| Lightspeed item | Quantity sold | Mapping quantity | Inventory deduction |
| --------------- | ------------: | ---------------: | -------------------- |
| Cola 0.33 l | 12 | 1 | 12 bottles |
| Espresso | 20 | 0.009 | 0.18 kg coffee beans |
### Recipe mapping
If the mapping points to a recipe, Mathership explodes the recipe and deducts all recipe ingredients.
| Lightspeed item | Quantity sold | Mapping | Inventory deduction |
| ---------------- | ------------: | ------------- | ------------------------- |
| Burger | 5 | Burger recipe | Ingredients for 5 burgers |
| Pizza Margherita | 3 | Pizza recipe | Ingredients for 3 pizzas |
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
| Lightspeed sale | Mapping | Inventory result |
| --------------- | ------------- | ----------------------------- |
| 1 × Espresso | Coffee beans | Deduct coffee beans |
| 2 × Cola 0.33 l | Cola bottle | Deduct 2 bottles |
| 1 × Burger | Burger recipe | Deduct all burger ingredients |
See [Ledger](/en/restaurants/inventory/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.
| Field | Meaning |
| ---------------- | ------------------------------------------ |
| Location | Lightspeed location |
| Report date | Date being processed |
| Request UUID | Shared identifier for the transfer request |
| Attempt number | Retry attempt number |
| Status | Processing, success, or failed |
| Ledger IDs | Created inventory ledger entries |
| Sales processed | Number of sales |
| Lines processed | Number of lines processed |
| Lines skipped | Number of skipped lines |
| Unmapped names | POS names without mappings |
| Error message | Failure reason |
| Response summary | Exceptions, recipes used, and API summary |
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.
| Alert code | Meaning |
| ---------------------- | -------------------------------------------------------- |
| `disconnected` | Refresh token is invalid and reauthorization is required |
| `token_refresh_failed` | Token refresh failed because of an auth or server error |
## 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
Choose a recent Lightspeed sales date with known sales.
Make sure the selected location has the correct storage unit.
Map a small number of important POS items first.
Run a manual transfer with force refresh.
Check created ledger IDs, unmapped names, and transfer statistics.
Confirm ingredient quantities and storage unit in the ledger.
Fix missing or incorrect mappings.
Confirm that corrected items now create ledger entries.
## Best practices
Create storage units, ingredients, and recipes before relying on Lightspeed transfers.
Connect and test one Lightspeed location first. After it works, continue with additional locations.
Start with the items sold most often. This creates the biggest inventory benefit quickly.
Always test one day manually before enabling automatic transfer.
Unmapped items are expected during setup. Use them as a working list for missing mappings.
Mapping depends on POS item names. If Lightspeed item names change, review mappings.
If authorization fails, reauthorize the existing integration. Deleting removes setup data.
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.
## Related pages
Return to the integrations overview.
Map POS items to ingredients or recipes.
Manage storage units used for Lightspeed deductions.
Review inventory movements created by Lightspeed transfers.