Retail API limitations and Questions

wncitwncit Member Posts: 5

Our client recently moved to Lightspeed as their point of sale. We are in the process of developing their booking engine for the different services they offer. In working with your API, we learned about your drip rate. I spoke with Arianne before the holidays and she said that we could request an increase to the drip rate. It looks like we start at 1, but can request an increase to 3. This helps, but it seems like the limitation would still create queue when integrating with your POS api. 

What options do they have in regards to the limitations of their api? Are there are other lightspeed solutions they should be looking at (They are not interested in 3rd party apps e.g. Booksy)

Below is an illustration of a basic service and a few comments :

Booking a 30 minute massage

1 lookup to see if a customer exists in Lightspeed.

1 Write to Lightspeed for create/update a customer.

1 Write to create a sale with line item 30 minute massage.

This is an example of the minimum information in a request. It’s assuming we don’t need to perform any additional lookups (pull the store, register or product codes because we have them stored on our end). It’s 21 points against our limit. So there’s a max of 2 simultaneous bookings we could ever handle with a count of 60. After that, we’ll need at least 21 total points to handle another booking. Assuming these totals for every booking, if we got a drip count of 3, we could in theory handle a max of 11 bookings a minute. That’s an absolute max and would only happen if someone booked at exactly the times we had enough points to book. So the practical minute to minute total would be fewer. With the current drip rate of 1, the highest possible bookings is 5 in a minute. Those numbers assume we start the minute with a full bucket. If we empty it, we could potentially get 8 bookings the following minute with a 3 drip rate and 2 bookings with the default 1 drip rate.

The 60 points is more of a general amount. It’s not always 60 points. Docs say it’s higher during off peek hours, but we’ve seen posts in the forums that the limit is actually lower during high traffic periods.

For Gift Cards and Discount

We also have discounts or gift cards work in this system. Gift cards appear to be based on physical cards, so I don’t know if it’s possible to just create one with their required characters. We couldn’t find a form in the light speed admin for gift cards for creating new ones. If we can, we’d need to expend a point on a lookup anytime they supplied us with a gift card. We’d need to do that before performing a transaction, then pass in the sale with the returned gift card id to have it remove the amount.

We’re going to have to actually try some of this to confirm it works, but I think the gift card management is possible. You can create a sale for a gift card and assign a code for it there (there’s a required format for gift cards). Through the api, gift cards involve creating a credit account attached to a customer account. If someone purchases a gift card from the site, there’s the normal stuff I’ve defined (account and sale call to api), and a third write to setup the credit account. So that’s at least 31 points of api calls. For someone to use the card, we’ll need to store the credit account’s id and the card code on our end so we can do a lookup to get the balance, then subtract it’s balance from the order, charge that amount with the payment gateway, then post the sale to Lightspeed with the credit account code of the gift card so Lightspeed will update its balance. So gift card usage will always involve an extra api point for the gift card lookup along with what’s normally used for the booking.

Also, I did find a way to define products with no inventory. I don’t know how that effects actual purchases since a sale record includes a price and a quantity (not sure if I can pass a quantity for a non-inventoried product). When you send a sale record, you pass a total but also the id and quantity of all the items purchased. Lightspeed uses the ids to lookup the prices of the products purchased to confirm they match the total you send. Since some activities can book multiple reservations in the same order, that’s analogous to purchasing multiples of a product while will need to line up in the api call. That hopefully works fine with non-inventory. 

In terms of components, everything we need appears to have a means to work with Lightspeed (except actually charging their card; we’ll have to do that separately). The issue still will be the throttling and how much overhead and possible slowdown for booking that will cause and what we do if we run out of points to make calls when a booking happens. If we queue everything, we’ll have the limitations of updates to their system all happening on an unknown delay. It’ll limit gift card usage since we have to perform a real time lookup on gift cards in order to use them; we’ll have to wait until they’re written to Lightspeed before they can be used. 

Let me know if all this makes sense.

Thanks for your assistance.


  • Hello @wncit,

    I apologize for the late response. Unfortunately, we won't be able to give you any rate increases at the time, but I can give you some advice about the flow so you only consume 11 points between looking for the customer and creating a sale and the customer in the same WRITE request. With the code below you can create the sale and customer at the same time, if you need to update the customer you will need to provide the customerID inside the Customer object.

    POST /API/Account/accountID/Sale.json

     "employeeID": 1,
     "registerID": 1,
     "shopID": 1,
     "completed": false,
     "Customer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "archived": "false",
      "customerTypeID": "0",
      "discountID": "0",
      "employeeID": "0",
      "taxCategoryID": "0"

    In the case for gift cards, you can use the same sale to create the gift card and add some balance to it.

    When you are using non-inventory items you still need to specify the quantity you are selling, but since there's no inventory you will not run out of items.

    In regards the default rate limits using the one on peak hours, it allows you to make a burst of 6 write request (10 points each one) but since each second you recover one point every 10 seconds you will have enough points to make a new request, allowing you a total of 12 write request, If there's a point where this is not enough even using the flow I mentioned at the beginning, you could reach out to me and I will make a request to our SRE team to see if you could apply for an increase.

  • wncitwncit Member Posts: 5

    So to make sure we're understanding correctly, when we do a sale and need to pass all the info to your end, we can generate the sale record, sale line items and customer all in the same call so we're only using one write per sale? And a customer insert vs update depends on passing in the customer id.

    With gift cards, we're looking at the tutorial at:

    It looks like here we need two writes for a gift card purchase; one to create the credit account and then a sale record with an embedded sales payment record it to put a balance on the card. The sale record like the first example could include the customer information of the person purchasing the card. Is that correct?

    If we want to try applying for an increase later, would that be for an increase in bucket size or drip rate?

  • [Deleted User][Deleted User] Posts: 0

    Hi @wncit,

    Exactly, creating a sales, adding saleline(s) and creating/updating a customer can be achieve with one POST request.

    Creating a gift card and adding fund to it can be done in 1 POST request to the Sale endpoint.

  • wncitwncit Member Posts: 5

    Do we embed the credit account object directly under the sale? The tutorial lists creating the account and defining the balance as separate operations and the docs for a sale and sale payment only lists a place to include the id of an existing account (under the sale payment or in a saleAccount under the sale payment). None mention including a full credit account object.

  • jodiejodie Member Posts: 1

    Alex and Julien~

    It is imperative that we have phone discussion by the end of this week!!

    We are at a standstill, as we have been for months due to Lightspeed 

    not answering our questions clearly as needed.

    Please let me know what day and time works for you and we will all make 

    time to discuss this matter on the phone.

    If Alex is unavailable, Julien I need to you to connect us with 

    developer that will talk with us via the phone this week.. as this can 

    no longer be put on the back burner. We need to move forward with this 

    project now.

    We will no longer tolerate the runaround! My family businesses financial 

    future is dependent upon the successful development of this software.

    Thank you for your timely response

    Jodie Appel

    Asheville Salt Cave'Owner

  • bibidilybibidily Member Posts: 6

    Can the customer object in this example include "contact" & "tags" payloads.

Sign In or Register to comment.