Stow jobs

This feature is only supported in the backend and usable via our stow job REST API.

Stow jobs represent the intention or instruction to change the storage location and/or the amount of stock in a facility. They support employees in a store or warehouse to execute one or several of the below tasks:

• relocate items within a warehouse

• stow items from a goods receipt

• discard expired or broken items

• create stock for items that are not registered yet

While the stow job itself holds general information such as the facility or priority of the job, the stow line item contains information on the items to be moved, their quantity, location, and more. Stow line items cannot exist without a stow job.

Description

Stow line items

A stow job can have 0 to n stow line items. While the stow job itself holds general information such as the facility or priority of the job, the stow line item contains information on the items to be moved, their quantity, location, and more. Stow line items cannot exist without a stow job.

The individual stow line items of a stow job can be started and completed in any order. Multiple line items can be in progress at the same time.

Instructive and operational data

Instructive data in the stow line item contains all information that an admin might want to write into a job so that her employees have all necessary information for performing the task. This covers data on the item to be moved such as scannable codes and information on the items, quantity, and locations that should be changed. The instructive data is divided into:

• takeFrom, covering everything relevant for taking items at the start of the job and

• stowTo, covering everything relevant for stowing the items or discarding them.

Operational data in the stow line item contains all information that is updated during the execution of the job. The operational data is divided into:

• taken, containing information on where (which stock or location) the item was taken from and how much was taken and

• stowed, containing information on where (which stock or location) the item was stowed and how much was stowed.

taken must always be provided either before or at the same time as stowed. If taken is provided separately from stowed a transfer stock is created internally representing the amount of goods which is currently in transit. The purpose of this stock is to keep the facility wide stock levels to change during the movement of goods.

Stowing types

Depending on the type of action that should be performed during the stow job, different types can be defined in the takeFrom and stowTo objects of the stow line item. The following types are available:

• LOCATION: Should be used if items should be taken from or stowed to a specific location but the exact stock that is chosen does not matter.

• STOCK: Should be used if items should be taken from or stowed to a specific location and the exact stock that is chosen matters. This could, for example, be the case if there are multiple expiry dates for the same item on one location. Can also be used if storage locations are not active on a tenant.

• UNREGISTERED: Should be used if new stock should be created for an item. This could, for example, be the case if items are found in a store that have not yet been booked into the systems. Can only be set as type for takeFrom. No stock or storage location can be set in the takeFrom object when using this type since a new stock will be created.

• DISCARD: Should be used if stock should be booked out of the systems and be discarded. This could, for example, be the case if items are broken or damaged. Can only be set as type for stowTo. No stock or storage location can be set in the stowTo object when using this type since the stock will be deleted.

Stow line items can be updated using the ModifyStowLineItemsAction.

Stowing status

A stow job can have one of the following status: OPEN, IN_PROGRESS, CANCELED, CLOSED, PAUSED. Status can be set externally via action (no status is set implicitly).

The stow job can only be set to a finalized state (CLOSED, CANCELED) if all stow line items are in a "coherent" state: Either nothing was taken or stowed, or the same amount was taken and stowed. This is done to prevent losing track of in-transit stock.

A stow job must be in status IN_PROGRESS for items to be taken or stowed.

The following state transfers are allowed:

from ⬇️ / to ➡️	open	in progress	canceled	closed	paused
open	yes	yes	yes	yes	yes
in progress	allowed if nothing was stowed already	yes	yes	yes	yes
canceled	no	no	yes	no	no
closed	no	no	no	yes	no
paused	allowed if nothing was stowed already	yes	yes	yes	yes

Stock updates via stow jobs

• Stock is updated after a stow line item was taken.

The target stock or location will not be updated until the items were stowed.

• Stock that has been already taken but has not been stowed or discarded yet is referenced in the heldItems object of the stow line item. In addition, the stock gets the "IN_MOTION" trait which makes it identifiable as a stock that is currently being moved and should not be updated.

• An internet connection is needed for starting and closing the job. However, stowing actions can also be performed without an internet connection. Results will be synced as soon as a connection is available.

External stock change reasons

There are reasons why stock is moved within a facility. Especially when goods are found, lost, or expire it is important to know why stock quantity changed or why stock was moved. Therefore, stow line items can optionally contain information on why the action was performed. It is possible to configure multiple reasons per stow line item, e.g., "expired" and "broken". Reasons are solely defined by the user. The fulfillmenttools platform does not react on stock change reasons.

Reasons must be configured via stock change reasons REST API before they can be used in stow jobs.

Create a stow job

To create a stow job, make a POST request to the /api/stowjobs endpoint.

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/stowjobs

The request body must contain the details of the job.

• If a listing is already defined for an article, it can be referenced by providing only the tenantArticleId. The remaining attributes are taken from the listing, but they can be overridden by including them in the request.

• The stowTo array can contain one or more objects if the items are being moved to different destination storage locations.

{
    "facilityRef": "YOUR_FACILITY_REF",
    "priority": 0,
    "shortId": "YOUR_SHORT_ID",
    "status": "OPEN",
    "stowLineItems": [
        {
            "article": {
                "tenantArticleId": "string"
            },
            "stowTo": [
                {
                    "quantity": 2,
                    "storageLocationRef": "DESTINATION_STORAGE_LOCATION_REF",
                    "type": "LOCATION"
                }
            ],
            "takeFrom": {
                "quantity": 2,
                "storageLocationRef": "SOURCE_STORAGE_LOCATION_REF",
                "type": "LOCATION"
            }
        }
    ],
    "targetTime": "1970-01-01T00:00:00.000Z"
}

A successful request returns a HTTP 201 Created status code and a response body representing the created stow job:

{
    "id": "71523fea-d80f-45e2-a128-9af163352db3",
    "created": "2024-12-16T12:00:38.362Z",
    "lastModified": "2024-12-16T12:00:38.362Z",
    "version": 1,
    "facilityRef": "YOUR_FACILITY_REF",
    "status": "OPEN",
    "stowLineItems": [
        {

Use case example

Relocate items between locations

An admin wants items from a goods receipt to be stowed or items to be relocated.

1. Create stow job using POST /api/stowjobs

   1. set status to OPEN

   2. use takeFrom.type LOCATION and stowTo.type LOCATION

2. Job is started by worker. Set status to IN_PROGRESS using StartStowJobAction.

3. Items are taken from start location. Set TAKEN information in operative data via ModifyStowLineItems action. A takenStockRef must be set to in order to define which stock should be reduced.

4. Items are stowed to target location. Set STOWED information in operative data via ModifyStowLineItems action.

   1. A stowedStockRef and stowedStorageLocationRef must be sent but can also be null.

   2. If a stowedStockRef is provided, the moved stock is added to the specified stock. If null, a new stock is created.

   3. If a stowedStorageLocationRef is provided, the stock will be created on that location. If null, a stock is created without a reference to any location.

5. Repeat step "3." & "4." until everything is stowed.

6. Set status to CLOSED via CloseStowJobAction.

Create stock for items that are not registered yet

An admin wants new stock to be booked to location.

1. Create stow job using POST /api/stowjobs

   1. set status to OPEN

   2. use takeFrom.type UNREGISTERED and stowTo.type LOCATION

2. If new stock should have properties or traits, it can be defined in the stockInformation of the takeFrom object.

3. Job is started by worker. Set status to IN_PROGRESS using StartStowJobAction.

4. Items are taken up by the worker. Set TAKEN information in operative data via ModifyStowLineItems action. A takenStockRef must be sent but can be null since a new stock will be created based on data in taken.takenQuantity and takeFrom.stockInformation.

5. Follow steps "4." to "6." from above.

Discard stock

Admin wants stock to be discarded.

1. Create stow job using POST /api/stowjobs

   1. set status to OPEN

   2. use takeFrom.type LOCATION and stowTo.type DISCARD

2. Job is started by worker. Set status to IN_PROGRESS using StartStowJobAction.

3. Items are taken from start location. Set TAKEN information in operative data via ModifyStowLineItems action. A takenStockRef must be set to in order to define which stock should be reduced.

4. Items are discarded. Set STOWED information in operative data via ModifyStowLineItems action. AstowedStockRefmust be sent but can be null since the stock is deleted after stowing was completed.

5. Set status to CLOSED via CloseStowJobAction.

Add a reason for changing a stow line item

Admin wants stock to be discarded and worker specifies a reason for discarding, e.g., "BROKEN".

1. Create stow job using POST /api/stowjobs

   1. set status to OPEN

   2. use takeFrom.type LOCATION and stowTo.type DISCARD

2. Job is started by worker. Set status to IN_PROGRESS using StartStowJobAction.

3. Items are taken from start location. Set TAKEN information in operative data via ModifyStowLineItems action. A takenStockRef must be set to in order to define which stock should be reduced.

4. Items are discarded and worker defined reason for discarding stock. Set STOWED information in operative data via ModifyStowLineItems action.

   1. AstowedStockRefmust be sent but can be null since the stock is deleted after stowing was completed.

   2. The reasons array of the corresponding stow line item can have one or multiple reasons. Each reason must be one of the following:

   3. An object containing id: <id> of a preconfigured (active) external stock change reason.

   4. An object containing tenantReasonId: <tenantReasonId> of an (active) preconfigured external stock change reason.

   5. An object containing reasonLocalized: <LocalizedString>. See Localization for the format of LocalizedString. For this option, the reason does not need to be preconfigured. The object can optionally contain a tenantReasonId, if there is no preconfigured external stock change reason with that Id.

5. Set status to CLOSED via CloseStowJobAction.

6. Follow the steps above.

Relocate items between stocks

Admin wants a specific stock to be relocated. This could, for example, be the case if there are multiple expiry dates for the same item on one location.

1. Create stow job using POST /api/stowjobs

   1. set status to OPEN

   2. use takeFrom.type STOCK and stowTo.type STOCK

2. Job is started by worker. Set status to IN_PROGRESS using StartStowJobAction.

3. Items are taken. Set TAKEN information in operative data via ModifyStowLineItems action. A takenStockRef must be set to in order to define which stock should be reduced.

4. Items are stowed. Set STOWED information in operative data via ModifyStowLineItems action. A stowedStockRef must be sent but can also be null.

If no stowedStockRef is defined, a new stock will be created.

1. Repeat step "3." & "4." until everything is stowed.

2. Set status to CLOSED via CloseStowJobAction.

Change the priority of a stow job

The priority can be defined on stowJob level. Any value can be set meaning users can define their own logic. Priority can be set using PATCH /api/stowjobs/{stowJobId}.

Relocate items from one to multiple locations

Admin wants items to be moved from one location to multiple other locations. This could, for example, be the case if items should be stored after a goods receipt was completed.

1. Create stow job using POST /api/stowjobs

   1. set status to OPEN

   2. use takeFrom.type LOCATION and stowTo.type LOCATION

   3. define all target locations along with the respective quantities in the stowTo array

   4. Job is started by worker. Set status to IN_PROGRESS using StartStowJobAction.

2. Items are taken from start location. Set TAKEN information in operative data via ModifyStowLineItems action. A takenStockRef must be set to in order to define which stock should be reduced.

3. Items are stowed to target location. Set STOWED information in operative data via ModifyStowLineItems action.

   1. Define the ID of the stowTo object that should be updated.

   2. It is necessary to send the complete stowTo array, even if only one object should be updated.

   3. A stowedStockRef and stowedStorageLocationRef must be sent but can also be null.

   4. If a stowedStockRef is provided, the moved stock is added to the specified stock. If null, a new stock is created.

   5. If a stowedStorageLocationRef is provided, the stock will be created on that location. If null, a stock is created without a reference to any location.

4. Repeat step "3." & "4." until everything is stowed.

5. Set status to CLOSED via CloseStowJobAction.