# Out of stock behavior and configuration

The out-of-stock behavior is a property of a `listing` that defines how the system handles orders containing a product that is currently unavailable for immediate shipment. A listing can be configured as backorderable, preorderable, restockable, or both preorderable and restockable.

If different out-of-stock rules are needed for different facility groups or orders, a `context` can be added to the configuration. This allows for more granular control over the behavior. More information is available in the section on [contextual configurations](#make-a-listing-preorderable-and-restockable-with-context).

## Make a listing backorderable

To make a listing backorderable, send a `PATCH` or `PUT` request to update the listing with the following JavaScript Object Notation (JSON) payload.

```http
PATCH https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings/{tenantArticleId}
```

```json
{
  "actions": [
    {
      "action": "ModifyListing",
      "outOfStockBehaviour": "BACKORDER"
    }
  ],
  "version": 2
}
```

## Make a listing preorderable

To make a listing preorderable, update the listing with the following payload. The `start` field within the `availabilityTimeframe` object specifies the date and time when picking can begin for the pre-ordered items.

```http
PATCH https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings/{tenantArticleId}
```

```json
{
    "version": 2,
    "actions": [
        {
            "action": "ModifyListing",
            "outOfStockBehaviour": "PREORDER",
            "outOfStockConfig": {
                "preorder": {
                    "availabilityTimeframe": {
                        "start": "2025-12-01T08:45:50.525Z"
                    }
                }
            }
        }
    ]
}
```

## Make a listing restockable

To make a listing restockable, update the listing with the following payload. The `restockableInDays` field defines the number of days until the listing can be replenished in the facility. A value of `0` is interpreted as the item being infinitely restockable.

```http
PATCH https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings/{tenantArticleId}
```

```json
{
    "version": 2,
    "actions": [
        {
            "action": "ModifyListing",
            "outOfStockBehaviour": "RESTOCK",
            "outOfStockConfig": {
                "restock": {
                    "restockableInDays": 5
                }
            }
        }
    ]
}
```

## Make a listing preorderable and restockable with context

To make a listing restockable and preorderable only in certain contexts, update the respective listing via PATCH or PUT with the below JSON body. In this example, the listing is only preorderable & restockable if its facility belongs to the [facility group](/documentation/getting-started/facilities/facility-groups.md) with ID "12345" AND the order does not have the [tag](/documentation/getting-started/tags.md) "click-and-collect". The priority is needed to ensure a clear sequence when considering the configuration in routing.

{% hint style="info" %}
More information on contexts can be found in the [Context article](/documentation/apis/context.md).
{% endhint %}

```http
PATCH https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings/{tenantArticleId}
```

```json
{
  "actions": [
    {
      "action": "ModifyListing",
      "outOfStockBehaviourByContexts": [
        {
          "priority": 1,
          "context": [
            {
              "type": "FACILITY_GROUP",
              "values": [
                "12345"  // ID of facility group.
              ]
            },
            {
              "type": "TAG_REFERENCE",
              "operator": "NOT",
              "values": [
                "click-and-collect"
              ]
            }
          ],
          "outOfStockBehaviour": "PREORDER_AND_RESTOCK",
          "outOfStockConfig": {
            "preorder": {
              "availabilityTimeframe": {
                "start": "2025-12-01T08:45:50.525Z"
              }
            },
            "restock": {
              "restockableInDays": 5
            }
          }
        }
      ]
    }
  ],
  "version": 2
}
```

## Define exceptions from out-of-stock behavior

To set exceptions from the out-of-stock behavior the `outOfStockBehaviour` in the `outOfStockBehaviourByContexts` must be set to `NONE`. In that case a `outOfStockConfig` must not be defined.

In the example below, the default behaviour for the listing is that it is restockable in 5 days. If the ordering facility belongs to the facility group **“12345”**, the listing is restockable in 4 days. If the ordering facility is part of the facility group **“6789”**, the listing is not restockable at all.

```http
PATCH https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/listings/{tenantArticleId}
```

```json
{
  "actions": [
    {
      "action": "ModifyListing",
      "outOfStockBehaviour": "RESTOCK",
      "outOfStockConfig": {
        "restock": {
          "restockableInDays": 5
        }
      },
      "outOfStockBehaviourByContexts": [
        {
          "priority": 1,
          "context": [
            {
              "type": "FACILITY_GROUP",
              "values": [
                "12345"  // ID of facility group.
              ]
            }
          ],
          "outOfStockBehaviour": "RESTOCK",
          "outOfStockConfig": {
            "restock": {
              "restockableInDays": 4
            }
          }
        },
        {
          "priority": 2,
          "context": [
            {
              "type": "FACILITY_GROUP",
              "values": [
                "6789"
              ]
            }
          ],
          "outOfStockBehaviour": "NONE"
        }
      ]
    }
  ],
  "version": 2
}
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fulfillmenttools.com/documentation/by-pillar/global-inventory-hub/stock/out-of-stock-behavior-and-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.