PHPackages                             timothydc/laravel-lightspeed-retail-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. timothydc/laravel-lightspeed-retail-api

ActiveLibrary[API Development](/categories/api)

timothydc/laravel-lightspeed-retail-api
=======================================

Laravel package for Lightspeed Retail API

v2.0.0(1y ago)121.1k↓47.2%9MITPHPPHP ^8.0

Since May 13Pushed 1y ago6 watchersCompare

[ Source](https://github.com/timothydc/laravel-lightspeed-retail-api)[ Packagist](https://packagist.org/packages/timothydc/laravel-lightspeed-retail-api)[ Docs](https://github.com/timothydc/laravel-lightspeed-retail-api)[ RSS](/packages/timothydc-laravel-lightspeed-retail-api/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (32)Used By (0)

laravel-lightspeed-retail-api
=============================

[](#laravel-lightspeed-retail-api)

[![Latest Version on Packagist](https://camo.githubusercontent.com/b6cf2b48c1d201a9e116b2fcf41c220efc0dab20db124e7a281b4e6e2376e432/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74696d6f74687964632f6c61726176656c2d6c6967687473706565642d72657461696c2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/timothydc/laravel-lightspeed-retail-api)[![Total Downloads](https://camo.githubusercontent.com/b95b82275dc1169a3b5b2d71523e5dfa2f5b6b23d7230f3043b1e796be1d69f5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f74696d6f74687964632f6c61726176656c2d6c6967687473706565642d72657461696c2d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/timothydc/laravel-lightspeed-retail-api)

Version Guidance
----------------

[](#version-guidance)

VersionPHP VersionLightspeed VersionSupportalpha^7.4 | ^8.02 | 3Unsupported since 2023-11-141.0^7.4 | ^8.02 | 3Unsupported since 2024-10-212.0^8.02 | 3New featuresThis package *should* be up to date with the [Lightspeed API changes from 2024-07-31](https://developers.lightspeedhq.com/retail/introduction/changelog/).

Installation
------------

[](#installation)

Via Composer

```
composer require timothydc/laravel-lightspeed-retail-api
```

Usage
-----

[](#usage)

For general information on how to use the Lightspeed Retail API, refer to the official [documentation](https://developers.lightspeedhq.com/retail/introduction/introduction/).

### Register API client

[](#register-api-client)

Before creating an API connection, you will need to sign up for an API client with Lightspeed Retail. You can do this via [the client portal](https://cloud.lightspeedapp.com/oauth/register.php).

The API client is developer friendly, you can set `https://your-domain.test` as your redirect URI. Remember the value of your redirect URI, we will need it later on.

### Configure .env

[](#configure-env)

After your API client is approved you will receive a `key` and `secret`. Add those values to your `.env` file.

```
LIGHTSPEED_RETAIL_API_KEY=xxx
LIGHTSPEED_RETAIL_API_SECRET=xxx
```

### Publish resources

[](#publish-resources)

You can publish all resources, or you may choose to publish them separately:

```
php artisan vendor:publish --tag="lightspeed-api"

php artisan vendor:publish --tag="lightspeed-api:config"
php artisan vendor:publish --tag="lightspeed-api:migrations"
```

The API tokens are stored in the database, by default. So run your migrations.

```
php artisan migrate
```

### Request initial access token

[](#request-initial-access-token)

Before we can request an access token you need to connect your Retail POS to this app.

You can manage the access level to your POS data via a scope. Choose a `$scope` from the options in `TimothyDC\LightspeedRetailApi\Scope`. More information on the scopes can be found in the [documentation](https://developers.lightspeedhq.com/retail/authentication/scopes).

#### Via command line

[](#via-command-line)

```
php artisan retail:auth
```

The command will ask you about the scope, and you will get an URL in return. Excellent deal!

#### Via controller

[](#via-controller)

```
use TimothyDC\LightspeedRetailApi\Scope;
use TimothyDC\LightspeedRetailApi\Facades\LightspeedRetailApi;

$scope = Scope::EMPLOYEE_ALL;

return redirect()->to(LightspeedRetailApi::redirectToAuthorizationPortal($scope));
```

After requesting your initial access token you will be redirected to the `Redirect URI`you provided when configuring your client information via the [Lightspeed Retail API Client](https://cloud.lightspeedapp.com/oauth/update.php).

### Configure routing

[](#configure-routing)

Register the following route in your `routes/web.php`. Update `your-redirect-uri` with the redirect URI you entered in the API client.

```
use \TimothyDC\LightspeedRetailApi\Http\Controllers\SaveAccessTokenController;

Route::get('your-redirect-uri', [SaveAccessTokenController::class, '__invoke']);
```

### Configure controller

[](#configure-controller)

The `SaveAccessTokenController` will store the initial access token and make follow-up request for the refresh token. Afterwards you will be redirected to `RouteServiceProvider::HOME`. If you would like to alter the redirect you may extend this controller.

### Make API calls

[](#make-api-calls)

You can now access the API. All resources return a [Laravel collection](https://laravel.com/docs/collections)... which means lots of fun!

```
use TimothyDC\LightspeedRetailApi\Facades\LightspeedRetailApi;

// get all
$account = LightspeedRetailApi::api()->account()->get();

// filter with GET with a limit and custom sorting (full details: https://developers.lightspeedhq.com/retail/introduction/parameters/)
$categories = LightspeedRetailApi::api()->category()->get(null, ['limit' => 10, 'sort' => 'name']);

// get category with ID 20
$categories = LightspeedRetailApi::api()->category()->get(20);

// same as above, but better
$categories = LightspeedRetailApi::api()->category()->first(20);
```

Note that not all [resources](https://github.com/timothydc/laravel-lightspeed-retail-api/tree/master/src/Services/Lightspeed) are added (yet). Feel free to add them yourself via a pull request! If you would like to filter the `GET`-results you can [look at the query parameters API](https://developers.lightspeedhq.com/retail/introduction/parameters/)

```
// advanced filtering

// get categories with an ID > 10
$categories = LightspeedRetailApi::api()->category()->get(null, ['categoryID' => ['operator' => '>', 'value' => 10]]);

// get products with their "Category" and "Note" relation
$products = LightspeedRetailApi::api()->item()->get(null, ['load_relations' => ['Category', 'Note']]);

// get sales sorted by timestamp in descending order
$sales = LightspeedRetailApi::api()->sale()->get(null, ['sort' => '-timestamp']);
```

#### Pagination

[](#pagination)

As of V3 of the Lightspeed Retail API the pagination works cursor based. The full details of on how pagination works, you can find in the [Pagination API documentation](https://developers.lightspeedhq.com/retail/introduction/pagination/)

```
use \TimothyDC\LightspeedRetailApi\Services\Lightspeed\ResourceSale;

$response = LightspeedRetailApi::api()->sale()->getWithPagination();

$attributes = $response['@attributes'];

// collect([
//      'next' => (request url),
//      'previous' => (request url),
//      'after' => (token),
//      'before' => (token),
//  ])

$sales = $response[ResourceSale::$resource];

// Sales data as a collection
```

To get the next page of the resource, add the 'after' token to your request.

```
$response = LightspeedRetailApi::api()->sale()->getWithPagination(null, ['after' => $attributes->after]);
```

The 'after' attribute will be empty on the last page and the 'before' attribute will be empty on the first page. This is the same as the 'next' and 'previous' attributes as described in the [Pagination API documentation](https://developers.lightspeedhq.com/retail/introduction/pagination/)

---

### Automatic model synchronisation \[optional\]

[](#automatic-model-synchronisation-optional)

If you would like to automatically synchronise your data to Lightspeed, you can add the `HasLightspeedRetailResources` trait and the `AutomaticSynchronisationInterface` interface to your model

In `getLightspeedRetailResourceMapping()` you want to map your model fields to the Lightspeed resource. The order of the resources is the order of the synchronisation. In the example below we put the manufacturer resource before the product resource because we need the `manufacturer id` for when we are syncing the product.

In `getLightspeedRetailResourceName()` you need to define the Lightspeed resource that represents your model. For example:

```
public function getLightspeedRetailResourceName(): string
{
    return \TimothyDC\LightspeedRetailApi\Services\Lightspeed\ResourceItem::$resource;
}
```

Don't forget to add the `HasLightspeedRetailResources` trait to your `manufacturer` resource too.

```
use TimothyDC\LightspeedRetailApi\Traits\HasLightspeedRetailResources;
use TimothyDC\LightspeedRetailApi\Services\Lightspeed\{ResourceItem, ResourceVendor};

class Product extends \Illuminate\Database\Eloquent\Model
{
    use HasLightspeedRetailResources;

    public static function getLightspeedRetailResourceMapping(): array
    {
        return [
            ResourceVendor::$resource => [
                ResourceVendor::$name => 'product_vendor'
            ],
            ResourceItem::$resource => [
                ResourceItem::$description => 'name',
                ResourceItem::$manufacturerId => ['manufacturer_id', 'manufacturer.id'],
                ResourceItem::$archived => ['active', 'archive'],
            ],
        ];
    }
}
```

You will notice some resources in the mapping have an array value. The first item in the array references the value which will be checked for a change, The second item is the value that will be sent to Lightspeed. It also accepts [mutators](https://laravel.com/docs/eloquent-mutators#defining-an-accessor):

In case of a relationship, the first value is the local foreign key. The second, is the related primary key.

```
public function getArchivedAttribute(): bool
{
    return $this->attributes['active'] === false;
}
```

By default, the synchronisation process listens to your model events `created`, `updated` and `deleted`. Update the array if you want to listen to other events.

```
use TimothyDC\LightspeedRetailApi\Traits\HasLightspeedRetailResources;

class Product extends \Illuminate\Database\Eloquent\Model
{
    use HasLightspeedRetailResources;

    public static function getLightspeedRetailApiTriggerEvents(): array
    {
        return ['created', 'updated', 'deleted'];
    }
}
```

If you would like to send fields to Lightspeed, even when the value isn't changed. You can add them to the `$lsForceSyncFields` array.

```
use TimothyDC\LightspeedRetailApi\Traits\HasLightspeedRetailResources;

class Product extends \Illuminate\Database\Eloquent\Model
{
    use HasLightspeedRetailResources;

    public array $lsForceSyncFields = ['ean'];
}
```

Change log
----------

[](#change-log)

Please see the [changelog](changelog.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [contributing.md](contributing.md) for details and a todolist.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Timothy De Cort](https://github.com/timothydc)
- [James Ratcliffe](https://github.com/jamesratcliffe) ()
- [All Contributors](../../contributors)

License
-------

[](#license)

MIT. Please see the [license file](license.md) for more information.

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance37

Infrequent updates — may be unmaintained

Popularity30

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 58.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~55 days

Recently: every ~157 days

Total

30

Last Release

574d ago

Major Versions

v0.23-alpha → v1.0.02024-10-20

v1.1.0 → v2.0.02024-10-21

PHP version history (3 changes)v0.1-alphaPHP ^7.4

v0.20-alphaPHP ^7.4|^8.0

v2.0.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/b19824d74959d87bb9c166a27875496cc58e9cc49e10fb551dea3d65f2bf30ad?d=identicon)[timothydc](/maintainers/timothydc)

---

Top Contributors

[![timothydc](https://avatars.githubusercontent.com/u/13786303?v=4)](https://github.com/timothydc "timothydc (14 commits)")[![brunogoossens](https://avatars.githubusercontent.com/u/1636664?v=4)](https://github.com/brunogoossens "brunogoossens (5 commits)")[![TVke](https://avatars.githubusercontent.com/u/15680337?v=4)](https://github.com/TVke "TVke (4 commits)")[![tarektaher](https://avatars.githubusercontent.com/u/3980870?v=4)](https://github.com/tarektaher "tarektaher (1 commits)")

---

Tags

laravellightspeed-retaillaravelretaillightspeedtimothydc

###  Code Quality

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/timothydc-laravel-lightspeed-retail-api/health.svg)

```
[![Health](https://phpackages.com/badges/timothydc-laravel-lightspeed-retail-api/health.svg)](https://phpackages.com/packages/timothydc-laravel-lightspeed-retail-api)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k7.6M74](/packages/openai-php-laravel)[statamic/cms

The Statamic CMS Core Package

4.8k3.2M720](/packages/statamic-cms)[flat3/lodata

OData v4.01 Producer for Laravel

96320.9k](/packages/flat3-lodata)[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

762.6k](/packages/scriptdevelop-whatsapp-manager)[njoguamos/laravel-plausible

A laravel package for interacting with plausible analytics api.

208.8k](/packages/njoguamos-laravel-plausible)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)