# Stow jobs {% hint style="info" %} This feature is only supported in the backend and usable via our [stow job REST API](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/stowjobs). {% endhint %} 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. ## 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 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 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. {% hint style="info" %} Stow line items can be updated using the `ModifyStowLineItemsAction`. {% endhint %} ## **Stowing status** A stow job can have one of the following status: `OPEN`, `IN_PROGRESS`, `CANCELED`, `CLOSED`, or `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. {% hint style="warning" %} A stow job must be in status `IN_PROGRESS` for items to be taken or stowed. {% endhint %} The following state transfers are allowed:
From ⬇️ / To ➡️OpenIn progressCanceledClosedPaused
Openyesyesyesyesyes
In progressallowed if nothing was stowed alreadyyesyesyesyes
Cancelednonoyesnono
Closednononoyesno
Pausedallowed if nothing was stowed alreadyyesyesyesyes
## Stock updates via stow jobs * Stock is updated after a stow line item was taken. {% hint style="warning" %} The target stock or location will not be updated until the items were stowed. {% endhint %} * 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](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/inventory-traits) 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. {% hint style="info" %} Reasons must be configured via [stock change reasons REST API](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/externalstockchangereasons) before they can be used in stow jobs. {% endhint %} ## Create a stow job To create a `stow job`, make a `POST` request to the `/api/stowjobs` endpoint. ```http 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. ```json { "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`: ```json { "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`](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). 3. Items are taken from start location. Set `TAKEN` information in operative data via [ModifyStowLineItems action](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). ### 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`](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). 4. Items are taken up by the worker. Set `TAKEN` information in operative data via [ModifyStowLineItems action](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](#relocate-items-between-locations). ### **Discard stock** Admin wants stock to be discarded. 1. Create stow job using [POST `/api/stowjobs`](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). 3. Items are taken from start location. Set `TAKEN` information in operative data via [ModifyStowLineItems action](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). A`stowedStockRef`must be sent but can be null since the stock is deleted after stowing was completed. 5. Set status to `CLOSED` via [CloseStowJobAction](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). ### 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`](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). 3. Items are taken from start location. Set `TAKEN` information in operative data via [ModifyStowLineItems action](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 1. A`stowedStockRef`must 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: ` of a preconfigured (active) [external stock change reason](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/external-stock-change-reasons). 4. An object containing `tenantReasonId: ` of an (active) preconfigured external stock change reason. 5. An object containing `reasonLocalized: `. See [Localization](https://docs.fulfillmenttools.com/documentation/getting-started/authentication-and-authorization/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](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/external-stock-change-reasons) with that Id. 5. Set status to `CLOSED` via [CloseStowJobAction](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). 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`](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). 3. Items are taken. Set `TAKEN` information in operative data via [ModifyStowLineItems action](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). A `stowedStockRef` must be sent but can also be null. {% hint style="warning" %} If no `stowedStockRef` is defined, a new stock will be created. {% endhint %} 5. Repeat step "3." & "4." until everything is stowed. 6. Set status to `CLOSED` via [CloseStowJobAction](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). ### 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}`](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#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`](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions). 2. Items are taken from start location. Set `TAKEN` information in operative data via [ModifyStowLineItems action](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/stowlineitems/-stowLineItemId-/actions). 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](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stowjobs/-stowJobId-/actions).