Out of stock behavior and 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.

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
}