> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lightspeed

> Integration details and setup guide for the Lightspeed connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Authorization Code with refresh tokens) or Bearer Token                                                                                                                                                                                                                                                                                                                                               |
| **Two-Way Sync**                    | No                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Events Supported**                | No                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Realtime**                        | Polling                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Supports Rate Limiting**          | Yes                                                                                                                                                                                                                                                                                                                                                                                                              |
| **Authentication Scopes Supported** | `employee:all`, `employee:register`, `employee:register_read`, `employee:inventory`, `employee:inventory_read`, `employee:reports`, `employee:admin`, `employee:admin_shops`, `employee:admin_employees`, `employee:admin_purchases`, `employee:admin_void_sale`, `employee:admin_inventory`, `employee:workbench`, `employee:customers`, `employee:customers_read`, `employee:customers_view_gift_card_numbers` |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **Lightspeed**:

* Custom actions and resources (refer to Lightspeed API documentation for available endpoints)

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                                                  |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Lightspeed Retail POS offers a 14-day free trial. Sign up at [https://www.lightspeedhq.com/pos/retail/](https://www.lightspeedhq.com/pos/retail/). |
| **Requires paid sandbox**                          | No. You can use the trial account for testing and development.                                                                                          |
| **Requires partnership to obtain authentication?** | No, but you must create a Lightspeed developer account to build OAuth apps.                                                                             |

***

### Authentication (OAuth 2.0)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

#### Create your OAuth app

1. **Create a Lightspeed Retail account** at [https://www.lightspeedhq.com/pos/retail/](https://www.lightspeedhq.com/pos/retail/)
2. **Sign up for a Developer account** at [https://cloud.lightspeedapp.com/developers/](https://cloud.lightspeedapp.com/developers/)
3. **Create a new application**:
   * Navigate to the Developer Portal
   * Click **Create New App**
   * Fill in your application details (name, description, website)
4. **Configure OAuth settings**:
   * Add the redirect URI: `https://api.runalloy.com/api/strategy/connector/lightspeed/callback`
   * Select the required scopes based on your needs (see scopes list above)
   * Note: Scopes are combined with `+` delimiter (e.g., `employee:all+employee:register`)
5. **Copy your OAuth credentials**:
   * Client ID
   * Client Secret
6. Configure these credentials in Alloy Automation

#### Obtaining an Account ID

* After OAuth authorization, you'll receive an `accountID` which represents the specific Lightspeed account
* This ID is required for making API calls and should be stored alongside the access token

#### API Documentation

* Lightspeed Retail API: [https://developers.lightspeedhq.com/retail/introduction/introduction/](https://developers.lightspeedhq.com/retail/introduction/introduction/)
* OAuth Guide: [https://developers.lightspeedhq.com/retail/authentication/authentication/](https://developers.lightspeedhq.com/retail/authentication/authentication/)
* API Reference: [https://developers.lightspeedhq.com/retail/endpoints/endpoints/](https://developers.lightspeedhq.com/retail/endpoints/endpoints/)

***

## Use Cases

### 1) Retail inventory synchronization

Sync product inventory levels, variants, and stock information from Lightspeed POS to your e-commerce platform, warehouse management system, or ERP for unified inventory management.

### 2) Omnichannel sales reporting

Aggregate sales data from Lightspeed POS locations with online sales channels to create comprehensive revenue reports and understand customer purchasing behavior across all touchpoints.

### 3) Customer data unification

Sync customer information, purchase history, and loyalty data from Lightspeed to your CRM or marketing platform to create personalized campaigns and customer experiences.

### 4) Automated reorder workflows

Monitor inventory levels in Lightspeed and automatically trigger purchase orders or restock notifications when products reach minimum thresholds, preventing stockouts.

### 5) Multi-location reporting

Pull sales, inventory, and employee data from multiple Lightspeed POS locations into a centralized business intelligence platform for enterprise-wide analytics and decision making.

***

## API Gotchas

* **Scope delimiter**: Lightspeed uses `+` as the scope delimiter instead of the more common space or comma. When requesting multiple scopes, combine them like `employee:all+employee:register+employee:inventory`.
* **Account ID requirement**: Many API endpoints require an `accountID` parameter, which represents the specific Lightspeed account. This ID is returned during the OAuth flow and must be stored for subsequent API calls.
* **Rate limiting**: Lightspeed enforces rate limits on API requests. The specific limits depend on your account plan. Monitor rate limit headers and implement exponential backoff to avoid throttling.
* **API versioning**: The Lightspeed Retail API is at version 3 (`/API/V3`). Always use the versioned endpoint to ensure consistent behavior. Future versions may introduce breaking changes.
* **Token refresh**: OAuth access tokens expire after a certain period. Implement proper token refresh logic using the refresh token to maintain uninterrupted API access.
* **Read vs write scopes**: Lightspeed provides granular read/write scopes (e.g., `employee:inventory_read` vs `employee:inventory`). Request only the minimum required scopes for your use case to follow the principle of least privilege.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.