Stock
Stocks represent items in a facility and carry information on how much of a product is present as well as metadata and operational data. Stock is typically linked to a listing which holds information on the attributes of the item within the facility. Only stock-specific information, which differs from item to item, like expiry dates or storage locations is tracked via stocks. Stocks can exist without listings and the other way around. However, we advise to always create listings for stocks so that stocks are assigned to the corresponding item and item information can be displayed in clients.
Description of stocks
Stock represents one or more items with the exact same attributes, e.g., items with the same expiry date, lying in the same storage location. Two stocks can be merged if all information on the respective stocks is identical, adding up their amounts. However, our systems still allow having two separate stocks with identical attributes.
The example below shows a listing with tenantArticleId "9999". As stocks for that item are firstly, distributed over two locations and secondly, have different attributes, three stocks were created.
Stock properties
Attributes which are relevant for operational processes are handled via Stock Properties. A common example for properties are values such as expiry date or batch number.
Stock receipt date
The receipt date represents the time and date when a stock enters a facility. The information can be used for various purposes, e.g., to ensure that picking follows a first-in-first-out strategy. This ensures that the timestamp is set to the value when the stock is accepted in the inbound process and not changed afterwards.
When the stock is created via stocks REST API, it is the responsibility of the integration layer to provide the correct time point. If no receiptDate is provided, the platform defaults to the moment when the stock is created.
Stocks with amount 0
The fact that there is no stock left for an item in a facility can be represented in two ways:
Having no stock entities
Having stock entities with amount 0
A stock with amount 0 that is assigned to a storage location can be used to indicate that the product should always be stored there. This is, for example, helpful when using the Operations App for picking or the Inventory App including storage location recommendations. If stock is set to 0, our systems will remove the stock entity by default. This can be prevented by adding the trait KEEP_ON_ZERO to a storage location.
Stock condition
It is possible that stock is delivered to a facility in a defective state or that it gets damaged during storage. In that cases, the stock condition can be set to "defective". Prior to setting a stock's condition to defective, it must first be marked as not pickable and not accessible. This ensures that the defective stock is no longer considered for sales processes. If rejected items are accepted during goods receipt, this stock is automatically marked as defective and labelled as not pickable and not accessible.
Create stock
To create stock, create a facility first, stock are always related to a specific facility.
To create stock, use the stocks endpoint and POST the amount of stock for each article for each facility:
After creating the stock, we receive a 201 CREATED response:
Besides some other properties, you might have noticed reserved and facilityWideReserved. When there is a PickJob inside the facility which needs this stock or this article in the facility, the stock will be reserved until it is picked. When the item is picked, the reservation will be removed and the amount of stock will be decreased.
Bulk stock create or update
When updating stock, it is recommended to use the bulk PUT /api/stocks endpoint to regularly push stock level updates by SKU (tenantArticleId) and facility while minimizing the number of calls.
In the following example, all stocks of tenantArticleId 4711 are updated.
The stock version and ID must be sent for an update. Otherwise, a new stock is created.
Search stock for obtaining the ID and version
First, stocks needs to be searched to obtain the IDs and versions of all stocks that exist for the respective tenantArticleId.
When stock should be updated per facility, the facilityRef must be included in the search query.
It might be necessary to iterate over multiple pages to get all stocks with the corresponding tenantArticleId. More information can be found under Pagination.
Update stock
Use the PUT /api/stocks endpoint to update stock.
The endpoint can be used for creating and for updating stocks (consider different input models).
Please be aware that an
IDandversionare necessary for updating stock as there can exist multiple stocks for the same SKU and facility.
More Stock-API information can be found here: REST API documentation - Stock
After creating the stock, a 200 OK response and the status UPDATED indicate a successful update.
The response includes additional fields that are automatically set. For example, the receiptDate is automatically set to the creation date of the stock. The traits automatically default to PICKABLE and ACCESSIBLE meaning that the stock will be available for incoming orders.
Versionless stock creation or updates
The UPDATE_VERSIONLESS action in the stock actions REST API enables versionless creation or update of stock quantities. This means users can update operations without without first retrieving the current stock version, helping reduce the total number of API calls.
Supports a maximum of 100 stock entries in a single request.
Executes with an all-or-nothing behavior; the request succeeds only if all stock records are processed.
Supports two operation types:
CREATE– Creates a new stock record for a specifictenantArticleIdandfacilityRef.UPDATE– Updates an existing stock record identified byid.
More Stock-API information can be found here: REST API documentation - Stock
To create or update stock without a version, use the endpoint of our API:
You can update stock that already has a version number using this endpoint.
The response format matches the structure of the stock upsert API.
Deleting stock by product/location/id in batch
To delete stocks by product, location or idm use the actions-endpoint of our API:
For deleting all stocks for a product in a facility, use the
DELETE_BY_PRODUCTSactionFor deleting all stocks on a storage location in a facility, use the
DELETE_BY_LOCATIONSactionFor deleting multiple stocks in a facility in one call, use the
DELETE_BY_IDSaction
Move stock to location
To move stock to a location, use the action MOVE_TO_LOCATION.
Note: In the options of the action the deleteFromStockIfZero is available. If this is set to true, the stock on the start location is deleted when value reaches 0, after move action was completed (even when the KEEP_ON_ZERO trait is active on the respective location).
Create safety stock
The PUT safetyStock endpoint lets us create the safety stock in a bulk operation:
The 207 MULTI-STATUS status code indicates success, the payload shows the status for each entity:
Last updated