Lightspeed Retail

Manage Lightspeed Retail products, inventory, customers, sales, promotions, fulfilment, and store credit

Connect Lightspeed Retail when a project needs data or workflows from an existing X-Series store. A Swarmz administrator configures the shared OAuth application once. Each workspace then authorises its own store, so the administrator's OAuth credentials identify Swarmz but don't grant access to every user's retail data.

Lightspeed remains hidden from workspaces until the OAuth application is verified and an administrator turns on its visibility. Connections belong to the workspace and can be linked to projects. This release supports shared project connections; it doesn't ask every end user of a published app to connect a separate Lightspeed account.

Configure the OAuth application

Create a Lightspeed Retail OAuth application by following the Lightspeed authorisation guide. In Swarmz:

Open Admin > Settings > Managed connector apps.
Select Lightspeed Retail.
Copy the Callback URL from Swarmz into the OAuth application.
Enter the application's client ID and client secret.
Enter a Test store prefix. For north-shop.retail.lightspeed.app, the prefix is north-shop.
Select Test & save, authorise that store, then enable the OAuth app.
Turn on Lightspeed visibility for Swarmz users.

The client secret is write-only. Swarmz stores it server-side and uses it only for OAuth code and refresh-token exchanges. If you remove, disable, or invalidate the OAuth application, new connections stay hidden or blocked; existing store grants remain separate records.

Available operations

Area	Read operations	Write operations	Limit per minute
Store setup	`get_retailer`, `list_outlets`, `list_registers`, `list_payment_types`	None	30
Products	`list_products`, `get_product`, `list_brands`, `list_price_books`	`create_product`, `update_product`	30 read, 10 write
Inventory	`list_inventory`	`create_stock_adjustments`	30 read, 10 write
Customers	`list_customers`, `get_customer`	`create_customer`, `update_customer`	30 read, 10 write
Sales	`list_sales`, `get_sale`	`create_sale`, `update_sale`	30 read, 10 write
Promotions	`list_promotions`, `get_promotion`	`create_promotion`, `update_promotion`	30 read, 10 write
Fulfilment	`list_fulfillments`	None	30
Gift cards and store credit	`list_gift_cards`, `list_store_credits`	`create_store_credit_transaction`	30 read, 10 write
Reference data	`list_suppliers`, `list_taxes`, `list_users`	None	30

Swarmz requests only the Lightspeed scopes needed for the selected read or write permission. See Lightspeed OAuth scopes for the provider's scope definitions. Requests use the connected store's validated *.retail.lightspeed.app host and the pinned API version. Request bodies are limited to 128 KB and provider responses to 2 MB.

Stock adjustments accept at most 100 items per call. DAMAGE, EXPIRY, INTERNAL_USE, THEFT, and DONATION require a negative quantity. STOCK_FOUND and SAMPLE_FOR_SALE require a positive quantity. See Lightspeed stock adjustments for provider fields.

Store-credit transactions require a customer, signed non-zero amount, transaction type, and a unique client UUID. ISSUE uses a positive amount, REDEMPTION uses a negative amount, and REVERSE preserves the sign of the transaction being reversed. Both issue and redeem scopes are required. See Lightspeed store-credit transactions for the provider contract.

Connect a Lightspeed store

In Settings > Integrations, select Lightspeed Retail, then select Connect new.
Enter a name that identifies the store or environment.
Enter the store prefix. Don't enter the complete hostname.
Choose read permission for dashboards and lookup tools. Add write permission for products, stock, customers, sales, promotions, or store-credit changes.
Complete Lightspeed's consent screen for that store.
Link the connection to the project when the AI requests it.

Swarmz stores the resulting access and rotating refresh tokens server-side. Reauthorise the connection if the grant is revoked or a refresh token can no longer be used.

Build with Lightspeed

Name the store workflow and the records the app should read or change. For example:

“Use Lightspeed Retail to build a catalogue and inventory screen with products, price books, outlet stock, and approved stock adjustments.”
“Build a customer service view that finds a customer, shows their sales, and updates their contact details.”
“Create a promotions console that lists campaigns and lets an approved manager create or update one.”
“Build a fulfilment dashboard grouped by outlet and register.”
“Create a store-credit tool that shows the current record and issues or redeems credit only after confirmation.”

The AI requests the Lightspeed connection when it reaches the first retail operation. Write operations require approval during the build and still depend on the scopes granted during OAuth consent.

Test Lightspeed Retail

Use a training store or disposable records for write checks.

Read the retailer, outlets, registers, and payment types. Confirm the returned store and outlet names.
List products and inventory, then compare one product's stock with Lightspeed Retail.
Create a disposable product, update it, and confirm both values in the catalogue.
Submit a one-item STOCK_FOUND adjustment with a positive quantity. Confirm the outlet stock change, then use the correct negative reason if you need to reverse it operationally.
Create a disposable customer and update its contact details.
Read a test sale and its fulfilment data. Create or update a sale only in a store prepared for test transactions.
Create a short-lived test promotion and confirm it appears in Lightspeed.
On a test customer, issue a small store-credit amount with a new client UUID, then redeem a smaller negative amount with another UUID. Confirm both transactions in Lightspeed.

If reads work and writes fail, reconnect with write permission and confirm the OAuth application includes the matching write scopes. If the client secret may have leaked, rotate it in Lightspeed, then enter the replacement in Managed connector apps and run Test & save again.