Stock Properties

This page contains information about benefits, usage and context of stock properties.

Introduction

Stock Properties allow tracking of specific values on a set of items, a Stock. They are represented by a map of key-value pairs, where keys can be either arbitrary or enforced to fulfill a predefined set. Both keys and values must be strings. You can of course use string representations of other data types like ISO-Date-Strings.

A common example for properties are values such as an Expiry Date or Batch Identifier.

Quick Start

• To get started using stock properties no special configuration has to take place

• Using the APIs listed in Providing values for properties you can provide the values in the appropriate fields

• If you want to make sure that specific properties are used, refer to #setting-constraints-and-validation

Providing values for properties

Any API which allows you to create stocks either directly or indirectly can work with properties

Creating Stocks

Create stock

POST/api/stocks

Body

application/json

facilityRef*string

tenantArticleId*string

value*integer (int32)

locationRefstring

propertiesall of

receiptDatestring (date-time)

customAttributesnullable object

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

Response

201401403

Stock was created.

Body

application/json

reserved*number

facilityWideReserved*number

available*number

id*string

version*number

facilityRef*string

tenantArticleId*string

tenantStockIdstring

created*string (date-time)

lastModified*string (date-time)

value*number

locationRefstring

traits*array of enum

scoresarray of string

scannableCodesarray of string

propertiesobject

serializedProperties*string

receiptDate*string (date-time)

customAttributesnullable object

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

Request

JavaScriptCurl

const response = await fetch('/api/stocks', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "facilityRef": "text",
      "tenantArticleId": "text"
    }),
});
const data = await response.json();

Response

{
  "reserved": 0,
  "facilityWideReserved": 0,
  "available": 0,
  "id": "text",
  "version": 0,
  "facilityRef": "text",
  "tenantArticleId": "text",
  "tenantStockId": "text",
  "created": "2024-04-29T06:48:52.032Z",
  "lastModified": "2024-04-29T06:48:52.032Z",
  "value": 0,
  "locationRef": "text",
  "traits": [
    "PICKABLE"
  ],
  "scores": [
    "text"
  ],
  "scannableCodes": [
    "text"
  ],
  "serializedProperties": "text",
  "receiptDate": "2024-04-29T06:48:52.032Z"
}

When creating stock you can provide the desired stock properties in the properties field of your request:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/stocks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "facilityRef": "<your facility>",
    "tenantArticleId": "<your tenantArticleId>",
    "value": 100,
    "properties": {
        "batch": "0-1-2-3",
        "expiry": "2023-08-17T09:39:28.966Z"
    }
}'

Receiving goods

There are multiple ways to create receipts besides the one linked and shown here. Stock properties can be added in the same manner via any of them. Please refer to the swagger documentation to learn more.

Swagger UI

When receiving goods, stocks containing the accepted goods are automatically created. To provide the properties for these stocks, you can include them in the stockProperties field of the receipt line item:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/receipts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "facilityRef": "<your facility>",
    "receivedDate": "2023-06-16T07:44:14.944Z",
    "receivedItems": [
        {
            "tenantArticleId": "apples-01",
            "acceptedQuantity": {
                "value": 1,
                "unit": "kg"
            },
            "rejectedQuantity": {
                "value": 0,
                "unit": "kg"
            },
            "comments": [],
            "stockProperties": {
                "batch": "2023-08-14-a"
            }
        },
        {
            "tenantArticleId": "oranges-01",
            "acceptedQuantity": {
                "value": 16
            },
            "rejectedQuantity": {
                "value": 0
            },
            "comments": [],
            "stockProperties": {
                "batch": "123-abc"
            }
        }
    ],
    "comments": []
}'

Setting constraints, validation

By default, any key can be used on each product and all keys are optional. The following section describes how you can have more control over which properties are allowed or required to be tracked for each product.

Often it is useful to limit and enforce which properties are tracked for which type of product. You can configure this using the stockProperties field on Listings. This field does not contain key-value pairs of property values but rather StockPropertyDefinitions. Each defines the following:

	Description
inputType	DATE or TEXT. The input type controls how values of this property should be treated by clients (i.e. show a date picker instead of a text field).
required	boolean. Creating a stock without providing a value for a required property will be forbidden and fail.
defaultValue	String or {{NOW}}which will be interpolated to current timestamp.

IMPORTANT

Constraints, validations as well as default values are ONLY applied on creation of stocks.

This means that existing stocks may still not have properties, even if required, or have properties which are - by a newer ruleset - not allowed.

If you do not want to enforce any constraints, just set the stockProperties field to null/undefined. Be aware, that stockProperties: {} is a valid configuration and will ensure that no properties are set!

Effects of properties on stock locations

🚧 TODO: Link mixed/unmixed storage config doc page :)

Special stock properties

While stock properties allow you to store any information that should be added to a stock, certain properties will be used by the system to inform decisions.

Property	Type	Function
expiry	DATE	Used in Routing / Picking to select best stock for First-Expired-First-Out strategies