Best Practices

Michael CareyMichael Carey Administrator, Lightspeed Staff Posts: 60 moderator
edited September 2017 in Tutorials
Please adhere to the following best practices when developing a new integration.

Respect Rate Limits

Lightspeed makes use of a leaky-bucket algorithm to control rate limiting (

In our implementation, PUT, POST, and DELETE requests are considered to be 10 units. GET requests are considered to be 1 unit. The default bucket size is 60 and the default drip rate is 1 / second, however the rate limits do fluctuate during off-peak hours.

The Lightspeed Retail API limits the number of requests that can be sent to an account over a period of time. When the rate limit has been reached, a 429 Rate Limit Exceeded error will be returned. If this error is encountered, don’t continuously hit the rate limit until you can make requests again. Have your code sleep until the required bucket level has been regained.

To view the current state of your bucket, retrieve the header information of the request made and look for the X-LS-API-Bucket-Level header to see how many points out of the current limit you have used.

To view the current drip-rate, look at the X-LS-API-DRIP-RATE header. Using the drip-rate, it is possible to calculate the amount of time needed to regain the required bucket space before sending a request.

Rate Limit Header Example
< HTTP/1.1 200 OK
< Date: Wed, 27 Jan 2016 16:46:01 GMT
* Server Apache/2.2.15 (CentOS) is not blacklisted
< Server: Apache/2.2.15 (CentOS)
< X-Powered-By: PHP/5.4.44
< X-LS-API-Bucket-Level: 10/60
< X-LS-API-Drip-Rate: 1
< X-LS-OAuth-Client-Id: 123456
< X-LS-Acct-Id: 123456
< Content-Length: 1575
< Vary: Accept-Encoding
< Content-Type: application/vnd.merchantos.pos-v1+xml
As you can see in the example above, 10 points out of the current bucket size of 60 have been used. Attempting to go above 60 will result in an error 429.

Only load needed relations

Loading all relations is acceptable during testing, but usually not all relations are needed when your code is finalized. Individual relations can be loaded by specifying them in a JSON encoded array. For example, if you wanted to only load the ItemShops relation, the parameter would be load_relations=[“ItemShops”]

Load Relations Example
Example URI:{account_id}/Item?load_relations=["ItemShops", "Tags"]

Example curl command:
curl -H 'Authorization: Bearer {API Key/OAuth Token}' -X GET{account_id}/Item?load_relations=\["ItemShops"\]

Inventory Adjustments

Adjustments to QoH (Quantity on Hand) should be done by creating and completing Sales with the appropriate items needing adjustment. This will create an appropriate record in Lightspeed for reporting purposes and show a proper record of the item being sold. Although it is possible to update QoH directly, this method is not recommended.
Post edited by Michael Carey on
Michael Carey

Product Manager
Lightspeed HQ


  • sgbitsgbit Partner Posts: 2

    We've recently switched to OAuth and it's working well, but I noticed the OAuth header we're sending is slightly different to what's recommended here.

    We're sending:
    Authorization: Bearer {OAuth Token}
    Should we change the type we're sending from Bearer to OAuth. Or are they interchangeable?

  • Michael CareyMichael Carey Administrator, Lightspeed Staff Posts: 60 moderator

    Thanks for pointing this out.

    On June 1, 2016, we updated our OAuth model to use the Bearer authentication scheme. Although both OAuth and Bearer are acceptable, using Bearer is the preferred method.

    I've updated the Best Practices document to reflect the new scheme.

    Michael Carey

    Product Manager
    Lightspeed HQ
Sign In or Register to comment.