# 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](https://docs.fulfillmenttools.com/documentation/getting-started/facilities/facility-groups) with ID "12345" AND the order does not have the [tag](https://docs.fulfillmenttools.com/documentation/getting-started/tags) "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](https://docs.fulfillmenttools.com/documentation/apis/context).
{% 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
}
```