Out of stock behaviour & configuration

The out-of-stock behaviour 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 behaviour. More information is available in the section on contextual configurations.

For more details on listings, refer to the Products – Listing documentation.

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.

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

{
  "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.

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

{
    "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.

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

{
    "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 with ID "12345" AND the order does not have the tag "click-and-collect". The priority is needed to ensure a clear sequence when considering the configuration in routing.

More information on contexts can be found here.

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

{
  "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 behaviour

To set exceptions from the out-of-stock behaviour 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.

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

{
  "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
}