> For the complete documentation index, see [llms.txt](https://docs.fulfillmenttools.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock.md).

# Stock

Stock represents items in a facility and includes information on how much of a product is present, along with metadata and operational data.

Stock is linked to a listing, which contains information about the item's attributes within the facility. Stock tracks only stock-specific information, which differs by item, such as expiry dates or storage locations.

Stock can technically exist without listings. However, we strongly recommend always creating listings for two reasons:

* Listings are required for order routing, as they contain data relevant to routing processes.
* Listings provide the corresponding product information to be displayed in the fulfillmenttools clients.

## Description of stock

Stock represents one or more items with the exact same attributes, for example, items with the same expiry date, lying in the same storage location. You can merge two stocks if all information on the respective stocks is identical, adding up their amounts. However, fulfillmenttools still allows having two separate stocks with identical attributes.

The example below shows a listing with `tenantArticleId` `9999`. Because the stocks for that item are first distributed across two locations and second have different attributes, three stocks were created.

<figure><img src="https://content.gitbook.com/content/Lrrr5jgTsDuR38gNJIrm/blobs/n6gKwlP7y59QkqrqI31F/image.png" alt=""><figcaption></figcaption></figure>

### Stock properties

Attributes that are relevant for operational processes are handled via [stock properties](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/stock-properties.md). Common examples include values such as expiry date or batch number.

### Stock receipt date

The receipt date represents the time and date when stock enters a facility. You can use this information for various purposes, for example, to ensure that picking follows a first-in, first-out strategy. This ensures the timestamp is set when the stock is accepted in the inbound process and not changed afterward.

When the stock is created via [stocks REST API](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/stocks), the integration layer must provide the correct time point. If no `receiptDate` is provided, fulfillmenttools defaults to the moment when the stock is created.

### Stock deletion

fulfillmenttools automatically deletes a stock entity when the following conditions are met:

* The stock value reaches `0`.
* The `KEEP_ON_ZERO` [trait](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/inventory-traits.md) is inactive on the stock (default behavior).

If reservations exist on a stock and the stock value reaches `0` without `KEEP_ON_ZERO` being active, the stock is no longer returned via the fulfillmenttools APIs. The reservation remains tracked in the system and is assigned to a suitable stock as soon as one becomes available.

### Stocks with amount 0

The fact that there is no stock left for an item in a facility can be represented in two ways:

1. Having no stock entities
2. Having stock entities with amount `0`

Stock with amount `0` that's assigned to a storage location can be used to indicate that the product should always be stored there. This is helpful, for example, when using the [Store Operations app](https://docs.fulfillmenttools.com/documentation/apps/store-operations-app.md) for picking or the [Inventory app](https://docs.fulfillmenttools.com/documentation/apps/inventory-app.md), including [storage location recommendations](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/storage-locations-and-zones.md#storage-location-recommendations). If stock is set to `0`, fulfillmenttools will remove the stock entity by default. This can be prevented by adding the [trait](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/inventory-traits.md) `KEEP_ON_ZERO` to a storage location.

### Stock condition

Stock may be delivered to a facility defective or damaged during storage. In that case, the stock condition can be set to `DEFECTIVE`. Before setting a stock's condition to defective, it must first be marked as not [pickable](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/inventory-traits.md#available-traits) and not [accessible](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/inventory-traits.md#available-traits). This ensures that the defective stock is no longer considered for sales processes. If rejected items are accepted during goods [receipt](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/inbound-process/receipts.md), fulfillmenttools automatically marks the stock as defective and labels it as not pickable and not accessible.

## Using stock endpoints

### Create stock

{% hint style="success" %}

#### Prerequisites

* Have at least one [facility](https://docs.fulfillmenttools.com/documentation/getting-started/facilities.md) created. Stock is always related to a specific facility.
  {% endhint %}

To create stock, use the stocks endpoint and `POST` the amount of stock for each article for each facility:

{% tabs %}
{% tab title="Endpoint" %}

```http
POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/stocks
```

{% endtab %}

{% tab title="Request" %}

```json
{
    "facilityRef": "{YOUR_FACILITY_REF}",
    "tenantArticleId": "SNEAK-W-4891",
    "value": 100,
    "properties": {
        "batch": "0-1-2-3",
        "expiry": "2026-08-17T09:39:28.966Z"
    }
}
```

{% endtab %}

{% tab title="Response" %}
After creating the stock, we receive a `201 CREATED` response:

```json
{
    "created": "2024-02-02T10:27:55.154Z",
    "facilityRef": "d286e108-698b-4f6c-97b7-21f090f17e46",
    "id": "33fb7ef6-47b5-4fd7-ac07-584293d84af3",
    "lastModified": "2024-02-02T10:27:55.154Z",
    "tenantArticleId": "BLAZER-G-6354",
    "value": 100,
    "scannableCodes": [],
    "scores": [
        {
            "type": "RATING",
            "name": "RECEIPT_DATE",
            "value": 3255
        }
    ],
    "reserved": 0,
    "facilityWideReserved": 0,
    "available": 100,
    "traits": [
        "PICKABLE",
        "ACCESSIBLE"
    ],
    "properties": {
        "batch": "0-1-2-3",
        "expiry": "2023-08-17T09:39:28.966Z"
    },
    "serializedProperties": "{}",
    "receiptDate": "2024-02-02T10:27:55.136Z",
    "version": 1
}
```

{% endtab %}
{% endtabs %}

Besides some other properties, you might have noticed `reserved` and `facilityWideReserved`. When a pick job inside the facility needs this stock or article, the stock will be reserved until it is picked. When the item is picked, the reservation is removed, and the stock amount is decreased.

### Bulk stock create or update <a href="#inventory-stock-sync" id="inventory-stock-sync"></a>

When updating stock, it's recommended to use the bulk `PUT` endpoint to regularly push stock level updates by SKU (`tenantArticleId`) and facility while minimizing the number of calls.

In the following example, all stocks of `tenantArticleId` 4711 are updated.

{% hint style="info" %}
The stock version and ID must be sent for an update. Otherwise, a new stock is created.
{% endhint %}

{% stepper %}
{% step %}
**Search stock for obtaining the ID and version**

To obtain the IDs and version of all the stock that exists for an item, use the stock search endpoint for the respective `tenantArticleId`.

{% tabs %}
{% tab title="Endpoint" %}

```http
POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/stocks/search
```

{% endtab %}

{% tab title="Request" %}

```json
{
  "query": {
    "tenantArticleId": {
      "eq": "4711"
    }
  }
}
```

{% endtab %}
{% endtabs %}

When stock should be updated per facility, the `facilityRef` must be included in the search query.

{% hint style="info" %}
You may need to iterate over multiple pages to retrieve all stocks with the corresponding `tenantArticleId`. See the [Pagination](https://docs.fulfillmenttools.com/documentation/getting-started/general-concepts.md#pagination) section for more information.
{% endhint %}
{% endstep %}

{% step %}
**Update stock**

To update stock, use the endpoint in the first tab. An example request and response are shown in the following tabs.

You can use the endpoint to create and update stock (see the different input models).

Note that an `id` and `version` are required to update stock, as multiple stocks can exist for the same SKU and facility.

{% tabs %}
{% tab title="Endpoint" %}

```http
PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/stocks
```

{% endtab %}

{% tab title="Request" %}

```json
{
  "stocks": [
    {
      "id": "{YOUR_STOCK_ID_1}",
      "value": 100,
      "version": 6
    },
    {
      "id": "{YOUR_STOCK_ID_2}",
      "value": 300,
      "version": 6
    },
    {
      "id": "{YOUR_STOCK_ID_3}",
      "locationRef": "SL-01",
      "properties": {
        "expiry": "2027-01-01T00:00:00.000Z"
      },
      "value": 200,
      "version": 6
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}
After creating the stock, a `200 OK` response and the status `UPDATED` indicate a successful update.

The response includes additional fields that are automatically set. For example, `receiptDate` is automatically set to the stock's creation date. The `traits` automatically default to `PICKABLE` and `ACCESSIBLE`, meaning that the stock will be available for incoming orders.

```json
[
    {
        "stock": {
            "created": "2025-11-06T13:11:35.738Z",
            "facilityRef": "{YOUR_FACILITY_REF}",
            "id": "{YOUR_STOCK_ID}",
            "lastModified": "2025-11-26T07:54:35.624Z",
            "tenantArticleId": "{YOUR_TENANT_ARTICLE_ID}",
            "value": 100,
            "locationRef": null,
            "scannableCodes": [],
            "scores": [
                {
                    "type": "RATING",
                    "name": "RECEIPT_DATE",
                    "value": 2602
                }
            ],
            "tenantStockId": null,
            "reserved": 0,
            "facilityWideReserved": 0,
            "available": 111,
            "traits": [
                "PICKABLE",
                "ACCESSIBLE"
            ],
            "traitConfig": null,
            "conditions": null,
            "properties": {},
            "serializedProperties": "{}",
            "receiptDate": "2025-11-16T07:46:16.215Z",
            "version": 7,
            "customAttributes": null,
            "availableUntil": null,
            "facility": {
                "facilityRef": "{YOUR_FACILITY_REF}"
            }
        },
        (...),
        "status": "UPDATED"
    }
]
```

{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

### Versionless stock creation or updates

The `UPDATE_VERSIONLESS` action in the [stock actions](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/stock-endpoints.md#post-api-stocks-actions) enables versionless creation or update of stock quantities. This lets you update operations without first retrieving the current stock version, reducing the total number of API calls.

The action:

* Supports a maximum of 25 stock entries in a single request.
* Executes with an all-or-nothing behavior. The request succeeds only if all stock records are processed.
* Supports two operation types:
  * [`CREATE`](#create-versionless-stock): Creates a new stock record for a specific `tenantArticleId` and `facilityRef`.
  * [`UPDATE`](#update-versionless-stock): Updates an existing stock record identified by the stock `id`.

#### Create versionless stock

To create versionless stock, use the endpoint in the first tab. An example request and response are shown in the following tabs.

{% tabs %}
{% tab title="Endpoint" %}

```http
POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/stocks/actions
```

{% endtab %}

{% tab title="Request" %}

```json
{
  "action": {
    "name": "UPDATE_VERSIONLESS",
    "stocks": [
      {
        "tenantArticleId": "Article-123", 
        "value": 20,
        "operationType": "CREATE",
        "facilityRef": "CGN-01"
      }
    ]
  }
}
```

{% hint style="info" %}
This example request use minimal information. You can add more fields than this. See the [actions endpoint](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/stock-endpoints.md#post-api-stocks-actions) for more details.
{% endhint %}
{% endtab %}

{% tab title="Response" %}

```json
{
    "name": "UPDATE_VERSIONLESS",
    "result": {
        "operationResults": [
            {
                "stock": {
                    "created": "2026-11-16T13:54:39.601Z",
                    "facilityRef": "{YOUR_FACILITY_REF}",
                    "id": "{YOUR_STOCK_ID}",
                    "lastModified": "2026-11-16T13:54:39.601Z",
                    "tenantArticleId": "Article-123",
                    "value": 20,
                    "reserved": 0,
                    "facilityWideReserved": 0,
                    "available": 20,
                    "traits": [
                        "PICKABLE",
                        "ACCESSIBLE"
                    ],
                    "receiptDate": "2026-11-16T13:54:39.586Z",
                    "version": 1,
                    "facility": {
                        "facilityRef": "{YOUR_FACILITY_REF}",
                        "tenantFacilityId": null
                    }
                },
                "status": "CREATED"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

#### Update versionless stock

To update versionless stock, use the endpoint in the first tab. An example request and response are shown in the following tabs.

{% hint style="info" %}
You can also update stock that already has a version number using this endpoint.
{% endhint %}

{% tabs %}
{% tab title="Endpoint" %}

```http
POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/stocks/actions
```

{% endtab %}

{% tab title="Request" %}

```json
{
  "action": {
    "name": "UPDATE_VERSIONLESS",
    "stocks": [
      {
        "id": "stock-id-123",
        "value": 20,
        "operationType": "UPDATE"
      }
    ]
  }
}
```

{% hint style="info" %}
This example request uses minimal information. You can add more fields than this. See the [actions endpoint](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/stock-endpoints.md#post-api-stocks-actions) for more details.
{% endhint %}
{% endtab %}

{% tab title="Response" %}

```json
{
    "name": "UPDATE_VERSIONLESS",
    "result": {
        "operationResults": [
            {
                "stock": {
                    "created": "2026-11-16T13:54:39.601Z",
                    "facilityRef": "{YOUR_FACILITY_REF}",
                    "id": "{YOUR_STOCK_ID}",
                    "lastModified": "2026-11-16T13:56:04.196Z",
                    "tenantArticleId": "Article-123",
                    "value": 20,
                    "reserved": 0,
                    "facilityWideReserved": 0,
                    "available": 20,
                    "traits": [
                        "PICKABLE",
                        "ACCESSIBLE"
                    ],
                    "receiptDate": "2026-11-16T13:54:39.586Z",
                    "version": 2,
                    "facility": {
                        "facilityRef": "{YOUR_FACILITY_REF}",
                        "tenantFacilityId": null
                    }
                },
                "status": "UPDATED"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

The response format matches the [stock upsert API ](https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/stock-endpoints.md#put-api-stocks)structure.

### Delete stock

To delete stock by product, location, or ID, use the stock actions endpoint:

```http
POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/stocks/actions
```

* To delete all stocks for a product in a facility, use the `DELETE_BY_PRODUCTS` action.
* To delete all stocks on a storage location in a facility, use the `DELETE_BY_LOCATIONS` action.
* To delete multiple stocks in a facility in one call, use the `DELETE_BY_IDS` action.

### Move stock to location

To move stock to a location, use the action `MOVE_TO_LOCATION`.

```http
POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/stocks/actions
```

Note: In the action `options`, `deleteFromStockIfZero` is available. If set to `true`, the stock at the start location is deleted when the value reaches `0` after the move action completes (even when the `KEEP_ON_ZERO` trait is active on the respective location).

### Create safety stock

The `PUT` safety stock endpoint lets us create the safety stock in a bulk operation:

{% tabs %}
{% tab title="Endpoint" %}

```http
PUT https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/safetystocks
```

{% endtab %}

{% tab title="Request" %}

```json
{
    "operations": [
        {
            "tenantArticleId": "SNEAK-W-4891",
            "facilityRef": "d286e108-698b-4f6c-97b7-21f090f17e46",
            "value": 10
        }
    ]
}
```

{% endtab %}

{% tab title="Response" %}
The `207 MULTI-STATUS` status code indicates success, the payload shows the status for each entity:

```json
[
    {
        "tenantArticleId": "SNEAK-W-4891",
        "value": 10,
        "status": "CREATED",
        "facilityRef": "d286e108-698b-4f6c-97b7-21f090f17e46"
    }
]
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
