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

availableUntilstring (date-time)

defines until when a stock is included in the stock availability as available and used for routing

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.

facilityRef*string

facility in which the stock is located

locationRefstring

location on which the stock is placed

propertiesall of

allow tracking of specific values such as expiry dates on a set of items. They should describe physical identifiable properties of the stock and are not meant to be used for metadata (see "customAttributes" for that).

receiptDatestring (date-time)

date-time when stock has entered the system, defaults to the creation date

tenantArticleId*string

tenantArticleId of the stock

traitConfigarray of StorageLocationTraitConfigEntry (object)

defines the traits of the stock, overrules the storage location traits

value*integer (int32)

Response

201401403

Stock was created.

Body

application/json

available*number

availableUntilstring (date-time)

defines until when a stock is included in the stock availability as available and used for routing

created*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.

facilityRef*string

facility in which the stock is located

id*string

lastModified*string (date-time)

locationRefstring

location on which the stock is placed

propertiesall of

allow tracking of specific values such as expiry dates on a set of items. They should describe physical identifiable properties of the stock and are not meant to be used for metadata (see "customAttributes" for that).

receiptDatestring (date-time)

date-time when stock has entered the system, defaults to the creation date

reserved*number

amount of this stock for customer orders

scannableCodesarray of string

scannableCodes such as barcodes that identify this stock

scoresarray of string

stock with a high score can used preferably over stock with a lower score in routing, depending on configuration. The score can represent different attributes of the stock like zone, storage location, expiry date or receipt date.

serializedProperties*string

properties object serialized as JSON string, sorted alphabetically by key

tenantArticleId*string

tenantArticleId of the stock

tenantStockIdstring

tenantStockId is an optional identifier for the stock in the tenant system, only set on stocks synced from listings

traitConfigarray of StorageLocationTraitConfigEntry (object)

defines the traits of the stock, overrules the storage location traits

traits*array of enum

provide information on how storage locations and stocks are to be handled in operational processes. Can only be set via storageLocation.

value*integer (int32)

version*number

Request

JavaScriptCurlPython

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

201401403

{
  "available": 0,
  "availableUntil": "2024-11-21T06:26:22.918Z",
  "created": "2024-11-21T06:26:22.918Z",
  "facilityRef": "text",
  "id": "text",
  "lastModified": "2024-11-21T06:26:22.918Z",
  "locationRef": "text",
  "properties": {
    "expiry": "text"
  },
  "receiptDate": "2024-11-21T06:26:22.918Z",
  "reserved": 0,
  "scannableCodes": [
    "text"
  ],
  "scores": [
    "text"
  ],
  "serializedProperties": "text",
  "tenantArticleId": "text",
  "tenantStockId": "text",
  "traitConfig": [
    {
      "enabled": false,
      "trait": "text"
    }
  ],
  "traits": [
    "PICKABLE"
  ],
  "version": 0
}

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 storage locations

The inventory configurations allow users to define the storage principles of their network or facility. If isMixedStorage is set to false, stock with the same tenantArticleId and different stockProperties should not be stored on the same location. Users will receive a modal warning them not to mix different properties on the same location when stowing in our inventory app or in the Backoffice. However, there is no technical constraint forbidding this behaviour.

In addition, if isMixedStorage is set to false, storage location recommendations are adapted so that no locations are recommended where the same item with different stockProperties is already stored.

For more information on inventory configurations please click here.

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