Important - changes to ItemShop for negative inventory

Our Lightspeed Retail developers have some good news!


Our team is working on supporting negative inventory on oversold or over-removed items through transfers and vendor returns. This new feature will incur the following changes to Lightspeed Retail’s item API endpoint.

1. The existing qoh field under ItemShop will display as negative if the item’s quantity on hand is negative as a result of sales, transfers or vendor returns. However, the qoh field cannot be updated to a negative value through the API.

2. A new read-only field called sellable will display the quantity of stock that a shop has available to sell. If you are connecting Lightspeed Retail to a solution that does not support negative inventory, this is the field you’ll want to use to fetch an Item’s stock.

Note: If you are looking at the ItemShop aggregate, the qoh field is the net total of all shops’ quantity on hand including any shops with negative inventory levels. The sellable field is an aggregate of all shops’ sellable stock and does not include shops with negative quantities in the calculation.


The BETA for the new negative inventory feature will begin with up to 100 customer accounts on April 3rd. However, all active accounts will have the new sellable field on April 3rd.


Please see the example response below.

{
  "@attributes": {
    "count": "1"
  },
  "Item": {
    "itemID": "19",
    "systemSku": "210000000019",
    "ItemShops": {
      "ItemShop": [
        {
          "itemShopID": "57",
          "qoh": "12",
          "sellable": "12",
          "backorder": "0",
          "componentQoh": "0",
          "shopID": 1,
          ...
        },
        {
          "itemShopID": "58",
          "qoh": "-5",
          "sellable": "0",
          "backorder": "0",
          "componentQoh": "0",
          "shopID": 2,
          ...
        },
        {
          "itemShopID": "56",
          "qoh": "7",
          "sellable": "12",
          "backorder": "0",
          "componentQoh": "0",
          "shopID": 0,
          ...
        }
      ]
    },
    "Prices": {
      "ItemPrice": [
      ...
      ]
    }
  }
}


13 comments

  • gregaricangregarican Member Posts: 533 

    When will the negative inventory changes hit the front-end web and iOS clients?

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

    Hi @gregarican,

    General Availability hasn't been set. We will work with Beta customer in an effort to release it to the rest of our customer by the end of summer.

  • gregaricangregarican Member Posts: 533 

    Great! I'll keep an eye out and apprise our staff of the pending changes.


    On a side note, this probably isn't the best place to put this. But working with API a lot it would be great if there were consistent behavior in passing back responses that have JSON array values.


    For example, if I'm parsing an array of product tags, I expect to see the JSON array values in brackets. But if there is only a single tag value, the JSON array value doesn't have brackets.

    "Tags":{"@attributes":{"count":"5"},"tag":["2000-to-5000","earrings","store-5a","yellow-gold","women"]}}}

    versus

    "Tags":{"@attributes":{"count":"1"},"tag":"women"}}}

    In order to gracefully work around this I have implemented custom JSON response handlers, but it'd be nice to not have to remember that extra gotcha :)

  • patmadiganpatmadigan Member Posts: 11

    I agree 100%. I came across this "feature" with Items, where a single record response was missing the extra pair of square brackets that were in the multiple record response. Yes, I wish they would fix this!

  • VanessaDVanessaD Moderator, Lightspeed Staff Posts: 202 moderator

    Hi Patmadigan!


    Yes, I wish they would fix this!

    The negative inventory module is currently available if you go into Settings / Optional Modules! If you'd like more documentation on this, you can check out our pages regarding how Neg Inv works, you can consult these :


    If there's something specific with your account you wanted us to look into, feel free to contact our support team so we can give you 1 on 1 help!

    ———


    If you have any further questions Please do not hesitate to contact LightSpeed support or check out our Support Page.


    Cheers!


    Vanessa D.

    Lightspeed Retail Support

    866-932-1801 ext. 2 (Toll-Free)

    514-907-1801 ext. 2 (Montreal)

  • gregaricangregarican Member Posts: 533 
    edited September 2019

    I agree 100%. I came across this "feature" with Items, where a single record response was missing the extra pair of square brackets that were in the multiple record response. Yes, I wish they would fix this!


    What I think @patmadigan is referring to is how the Lightspeed Retail API response sets are inconsistent when it comes to array values. If only one item is an array then the value isn't passed back as an array with a single member. It's passed back as a singleton.


    If you look at my post previous to his you'll see an example of what I'm talking about. I had to code and reuse a custom handler for this gotcha. Here is a basic example:


    "Element": ["one", "two", "three", "four] <= this is an array of multiple elements that would be returned by the API

    "Element":["one"] <= this is an array that contains a single element that should be returned by the API

    "Element":"one" <= this is what the API returns instead. Inconsistent and breaks things without working around

  • VanessaDVanessaD Moderator, Lightspeed Staff Posts: 202 moderator

    Thanks for the feedback, Greg!


    I'll ask that one of our API guys take a look at this query so that they can help you guys determine what's happening here.

    ———


    If you have any further questions Please do not hesitate to contact LightSpeed support or check out our Support Page.


    Cheers!


    Vanessa D.

    Lightspeed Retail Support

    866-932-1801 ext. 2 (Toll-Free)

    514-907-1801 ext. 2 (Montreal)

  • LeahLeah Moderator, Lightspeed Staff Posts: 194 moderator

    Hi @gregarican @patmadigan, we do have an enhancement request on file to consistently return an array regardless of whether there is a single element or multiple elements being returned. I will create you both tickets to attach to the enhancement request.

    API Support
    Lightspeed HQ
  • patmadiganpatmadigan Member Posts: 11

    I don't believe that I have received any notification of a ticket being requested. Any updates on this issue?


    I have only recently gotten back to working with the LightSpeed Retail API, and I just encountered a similar issue with ItemVendorNums returning inconsistent JSON data for 1 vs. multiple ItemVendorNums per Item. So the bug seems to still be there.


    thanks,

    Pat

  • gregaricangregarican Member Posts: 533 

    I have to create a generic method that correctly accounts for these inconsistent response elements. Just call that method when parsing the numerous elements that could be an array. Pretty clumsy but it works.


    Too bad the API isn't cleaned up to adhere to standard expectations :)

  • LeahLeah Moderator, Lightspeed Staff Posts: 194 moderator

    Hi @patmadigan I sent you a follow up email on September 13th, 2019 to the email address on file for your account on our community. The subject line reads "Consistently return array." I will bring this issue to the attention of our dev team but would like to point out it is considered an enhancement request and not a bug. In the meantime you can create a method to manage these responses, as mentioned above.

    API Support
    Lightspeed HQ
  • gregaricangregarican Member Posts: 533 

    Butting in on my part, but I think it's up for debate that consistent API behavior that aligns with standard JSON-API specs is an enhancement. This goes back to spec discussions from 2014 --> https://github.com/json-api/json-api/issues/268.

    Note: I've worked with roughly a dozen different third party API's and found that only Lightspeed's strays from the standard behavior. Basically, any element that can be an array will always be passed as an array.

  • patmadiganpatmadigan Member Posts: 11

    Thanks Leah. That email would have gone to my boss, that explains why I didn't receive it.

    I did go ahead and change my code to include the square brackets for the JSON data, and it's working fine with that.

    I agree with @gregarican ; I would call this a bug.

    thanks,

    Pat

Sign In or Register to comment.