Stock Properties

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

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

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

Body

availableUntilstring · date-timeOptional

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

customAttributesobject | nullableOptional

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.

facilityRefstringRequired

facility in which the stock is located

locationRefstringOptional

location on which the stock is placed

propertiesall ofOptional

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-timeOptional

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

tenantArticleIdstringRequired

tenantArticleId of the stock

valueinteger · int32Required

Responses

201

Stock was created.

application/json

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this

application/json

post

HTTPcURLJavaScriptPython

POST /api/stocks HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 291

{
  "availableUntil": "2025-05-12T11:15:49.325Z",
  "conditions": [
    "DEFECTIVE"
  ],
  "customAttributes": {},
  "facilityRef": "text",
  "locationRef": "text",
  "properties": {
    "expiry": "text"
  },
  "receiptDate": "2025-05-12T11:15:49.325Z",
  "tenantArticleId": "text",
  "traitConfig": [
    {
      "enabled": true,
      "trait": "text"
    }
  ],
  "value": 1
}

{
  "available": 1,
  "availableUntil": "2025-05-12T11:15:49.325Z",
  "conditions": [
    "DEFECTIVE"
  ],
  "created": "2025-05-12T11:15:49.325Z",
  "customAttributes": {},
  "facilityRef": "text",
  "id": "text",
  "lastModified": "2025-05-12T11:15:49.325Z",
  "locationRef": "text",
  "properties": {
    "expiry": "text"
  },
  "receiptDate": "2025-05-12T11:15:49.325Z",
  "reserved": 1,
  "scannableCodes": [
    "text"
  ],
  "scores": [
    "text"
  ],
  "serializedProperties": "text",
  "tenantArticleId": "text",
  "tenantStockId": "text",
  "traitConfig": [
    {
      "enabled": true,
      "trait": "text"
    }
  ],
  "traits": [
    "PICKABLE"
  ],
  "value": 1,
  "version": 1
}

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