Input wanted: Change of endpoint InventorySummary

[Thomas Skjørten]

Greetings all Visma.net API users!

The endpoint InventorySummary is one of the most used endpoints we have in the API today with millions of calls being made every week. We know that the current implementation of the endpoint is not optimal for your integrations, and we are therefore planning to implement a new version. 

To make sure the new version will be the best possible solution for your use cases we would like to have your input on how the ideal signature and functionality should be. 

The current endpoint has the following signature:

GET /controller/api/v1/inventorysummary/{inventoryNumber}[?warehouse=*&location=*]

With this structure you are only able to ask for the summary of one item per call, optionally limited to one warehouse and/or one location.

Our goal is to make the new endpoint the best suited for your use cases, while at the same time improving the performance of the call and reducing the number of calls needed to perform the use case.

Please provide information on your use case and the change needed to best suit your integration.

Your input in this thread would be much appreciated!

[krihett]

We would appreciate some more functionality to this endpoint.

Use case 1: A user wants to know which products exists (and how much) on a location.
Like https://integration.visma.net/API/controller/api/v1/inventorysummary/?warehouse=1&location=1

Use case 2: A user wants to know the summary of a list of (similar) products. Like a shoe of the same type, but different sizes and colors.
Instead of making several calls to the endpoint one by one, we would like to make one call with a list of products. Like https://integration.visma.net/API/controller/api/v1/inventorysummary/?warehouse=1 + a list of products

Use case 3: Compare the balance in Visma.net to the balance in a third party warehouse management system.
Would like the endpoint to return a summary for the whole warehouse, like https://integration.visma.net/API/controller/api/v1/inventorysummary/?warehouse=1

[Roland van Belle - Consolit]

We are missing the lot/serial number functionality. Expand by lot/serial number (ScreenId=IN401000).

This feature allows us to retrieve stock by lot/serial number.

[Roland van Belle - Consolit]

Can somebody update us about the missing lot/serial number functionality?

We really need this (very urgent) for our solutions!

[Magnus Johnsen]

We have asked the team for an update on a possible ETA. Information will be posted in the Idea's thread when we have more information. If you have any concerns regarding the time to implement this, we recommend that you contact your partner service. 

[Yıldırım]

Request: Webhooks support for "inventorySummary" endpoint. 

Implementation of this will eliminate the unnecessary traffic caused due to polling that the client makes in order to be able to get the latest inventory status. A push notification sent via the webhook when changes have been made would be beneficial for both side, and providing the customer with at better experience of integrations.

[Thomas Skjørten]

Input from BX Software (Sven Tore Iversen):

We believe inventory summary is lacking in two main categories.  Listing them is easy enough: speed and information detail. 

We can list a lot of use cases, but I think the important requirements boils down to fetching a list, with valid filters in a single request, and exposing the details of the allocations of each location. Another step to reduce the load of inventorySummary is to improve on other endpoints, eliminating the need to “abuse” the endpoint.

I see three different usage scenarios for stock quantity information.

1. Lite: You only need total stock amount, either total or based on a specific store/warehouse.
   Typical use case: Sales, webshop, mobile device etc.
   
   Details about soBooked etc is often important, dependent of the consumer and use case. Some customers want the actual stock amount, some want what is available for sales (stock – sales order etc) and some want what’s available for future stock (add incoming POs). Dependent on the data structure I guess that being able to skip inPO/inTransit etc could reduce the load. I expect all 3^rd parties to be happy to specify url parameters to let you know if e.g. incoming and/or outgoing is needed.
   The inventory/ endpoint supplies this information, and the inventorySummary could probably be skipped. However, it’s currently not possible to get only the basic stock quantities, without getting the product information. (if product information itself is not needed fetching them is an unneeded cost)
   
   
2. Medium: This is basically the use case the endpoint supports today. We get stock information + location information in the warehouse. In a warehouse application/scenario this is very important for customers using more than one location for their goods. Other warehouse customers could live very happily with “lite” or “no” use of inventorySummary, since the stock amount is not really needed (most scenarios) for either receiving, picking or even stocktake. In this scenario the usage of inventorySummary is working for what it is intended to do (I guess), but it’s not doing it very efficient. We have also been “abusing” the endpoint due to missing functionality/information in other endpoints.
   
   
3. Advanced: In a warehouse application, typical for our customers, this is one of the most critical issues with Visma.Net: It’s not possible to get the allocation details from inventorySummary. The endpoint gives you information about how much is stored on a given location, but not what batches/serial-numbers or expirationDate hit has. In the UI you must specify that you need the allocation details, but the API is missing this feature.
   Sample usage scenarios that are not supported:
   
   A: Stock Movement. Before doing stock movement it is important to validate that the stock is not reserved on an active delivery etc. Getting the “free” stock for a specific batch on a location is much more efficient than getting all shipments, with lines, to compare if the serial number is assigned to any of them. Giving the user a change to verify this before confirming a lot of lines on a device is helpful.
   
   B: Stock Validation: Especially with fresh food, flowers and other high turnover goods it’s common to do a stock validation. Not a stock take. Locations are often floating zones, and when you have some time you scan a product/batch to see what location it’s supposed to be placed at. You can’t really halt production to do a stocktake, and it’s not always about counting, but more about “cleanup” or evaluating if a stocktake is needed.
   
   

C: When picking without reservations, either when needing to select another allocation on a shipment or when doing picking based on orders, before creating shipments. (When the warehouse needs the ability to add products lines on the order while picking)

All scenarios would greatly benefit from common improvements.

1. Listing/Paging. Today we need to do a single get per product, per warehouse. When counting requests. A customer with 30k products, and 10 warehouses. Needs a few requests. When including the request going to Inventory to fetch the actual product information we get 300.060 request. And still don’t have the allocation details. Queuing the request and having an average request time of around 0.5sec sets the initial sync for a new customers to 41,7 hours. The first stock value is obviously outdated at this point.
   Single get requests might be easier for the SQL server, but the overhead and load of the API itself must be noticeable. Even though you could to optimization on the request you still have to overhead of the request, and the client library etc. A 200% speed increase would not give 200% improved performance for the end user. If increasing the overall speed to much the customer will simply hit the rate limiter instead. Listing is key, paging is fine.
   
   

Implement availabilityLastModifiedDateTime in inventorySummary. Eliminate the need to use inventory to prefetch a list of products we need to fetch from inventorySummary. Combine the listing with this would reduce the following scenario from 301 to 1 request:
Get all products from inventory/ where stock value is changed the last hour/minutes etc.
Enumerate list returning 100 items with updated stock, fetch inventorySummary for 100 products, and 3 warehouses, with a total request count of 301.

[Kjetil Ringstad]

Please include the report parameters available from ScreenID IN61500S.

[Trygve Storrønningen1]

Hi Thomas

Correct and reliable information about the availability of goods is essential for any seller and buyer, so thank you very much for paying due attention to this matter.

Before focusing on the implementation details and signature of the endpoint, please consider the following basic use cases. They should be applicable to any solution which presents inventory items from Visma.net for online sale to end users, and they are described with the point of view of such customers in mind, e.g. interacting with a webshop application.

Use case 1: Browsing or searching for products.

• At this stage, the customer might be interested in knowing about which products are available for purchase immediately, and which are not - with or without details about future availability. The customer may or may not be interested in availability at particular locations / warehouses.
• A typical service call might include a large list of product (inventory item) numbers, for any number of locations / warehouses.

Use case 2: Looking at individual products.

• At this stage, the customer is beginning to decide which product(s) to actually buy. Availability at particular locations / warehouses, as well as details about future availability may be important to some (e.g. if considering click-and-collect options, or looking for the seller who can deliver the most recent PlayStation quickest).
• A typical service call might include one or a small list (in case of bundle or variant products) of product (inventory item) numbers, for any number of locations / warehouses. A detailed response may be required, so that sufficient options can be presented to the customer to maintain interest.

Use case 3: Creating an order.

• At this stage, it might be crucial for the customer to be informed about any product(s) which can and cannot be delivered immediately - e.g. if that PlayStation of which there was only one remaining unit in stock a few minutes ago has been sold, and no delivery can be expected for several weeks or months.
• A typical service call might include a list of product (inventory item) numbers, for any number of locations / warehouses. Accurate information is critical, and a detailed response may be required, so that sufficient options can be presented to make sure the customer completes the order.

Use case 4: Filtering for only in-stock products.

• Customers value their time, and some are only interested in buying products which can be delivered immediately. In this case, product availability should be known in advance so that it may be filtered upon when performing queries, rather than querying first and then calling your endpoint to check for availability (which would impact performance and responsiveness adversely).
• Typical service calls might include regular pagination of data, with or without filter parameters and/or a last modified datetime parameter.

The above use cases differ in terms of how they translate into inventory summary service calls in several ways which should be analyzed and understood. A good implementation may be driving sales and customer retention, while a poor one may be losing both.

General considerations

Product availability is highly volatile information which can change rapidly and by significant amounts. It is also critical information to customers, in that unavailability of certain products may be a deal-breaker, making the customer not commit to a purchase if available products are falsely presented as unavailable - or disappointing and potentially losing the customer if unavailable products are falsely presented as available.

You must therefore take necessary steps to understand and cater well for the realistic use cases, so that it is easy for integrators to meet our clients' requirements while at the same time not abusing your services (or incurring large costs for high-volume use).

We understand that our implementations should be able to minimize load on your services, but at the same time our need for reliable and up-to-date data must be understood and met.

We are aware of web hooks, but until they can be relied upon 100.00% (and for other reasons) other mechanisms that can handle the pressure must be available as well.

Extra information like restockability and expected longevity might also be relevant and useful information (e.g. to decide how often to refresh cached data)

[Trygve Storrønningen1]

A change of this endpoint is very much welcome 🙂  

You say it is one of the most used endpoints, but we are not using inventorySummary at all as of today.

We need to be able to do delta imports and to GET based on minimum these additional filtering:

• availabilityLastModifiedDateTime (stock)
• availabilityLastModifiedDateTimeCondition (stock)
• lastModifiedDateTime (product)
• lastModifiedDateTimeCondition (product)
• inventoryNumber
• list of inventoryNumber
• attributes (product)
• pageNumber
• pageSize

I guess you already got this noted, but this is just a quick top-of-the-head response

We will document use cases today, and hope to get some more detailed response later today 🙂

When this is implemented; it might also be an idea to make the /inventory endpoint less expensive by making the warehouseDetails optional

Please also consider POST to GET.

PS!
Before you start working on this or any new endpoint; please fix the failing implementation of the same filtering options on other endpoints 😉

-- Plust REST nactos, plus spei nactos!