# Stock reservations

Stock reservations typically are used to [reserve the stock](https://docs.commercelayer.io/core-api-reference/reserved_stocks) associated with [an order's line items](#line-item-stock-reservation) of type `skus` or `bundles` until the order is approved, so that product availability is accurately reflected throughout the order lifecycle. If needed, you can also create stock reservations that are [not associated](#generic-stock-reservation) with a specific order's line item.

{% hint style="warning" %}
Active stock reservations (if any) determine the actual availability of the associated [stock items](https://docs.commercelayer.io/core-api-reference/stock_items). The available stock quantity is equal to the stock item quantity minus the reserved stock quantity.
{% endhint %}

{% hint style="info" %}
Stock reservations act on the whole line item quantity. If the available stock is split between different stock locations, multiple stock reservations are created.
{% endhint %}

## Line item stock reservation

### Automatic stock reservation at order placement

When the order is placed, any existing active stock reservation associated with its line items is moved from `draft` to `pending`. If no draft stock reservation is associated with the order's line items, the stock reservations needed to block the whole order's stock are automatically created in `pending` status, and the associated stock is reserved without decrementing the stock item quantities. Once the order is approved, the stock item quantities are decremented and the involved stock reservations are deleted, unless you have chosen to manually manage these actions by setting the related flag at the [inventory model](https://docs.commercelayer.io/core-api-reference/inventory_models#manual-stock-decrementation) level. If the order is cancelled before approval, the reserved stock is released, becoming available again, and the involved stock reservations are deleted.

<figure><img src="https://4223484328-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWJeylueWkzLadK710XZ%2Fuploads%2FC4cPUd1lE8Ie9Pr24P6E%2Fstock-reservations-diagram.jpg?alt=media&#x26;token=20afab7d-b3fe-4f0e-be7d-24fb1a6a1205" alt=""><figcaption></figcaption></figure>

### Manual stock reservation before order placement

You can temporarily reserve the stock associated with a line item before the order placement (e.g. to handle pre-orders) by sending a specific [trigger attribute](https://docs.commercelayer.io/core-api-reference/line_items#reserving-the-stock) when adding the line item to the order. This way, the necessary stock reservations are created in `draft` status, with an expiration date of **1 hour** (you can change the default value at the [inventory model](https://docs.commercelayer.io/core-api-reference/inventory_models#stock-reservation-settings) level). If the order isn't placed before the expiration date or the line item is removed, the corresponding reserved stock is released, and any associated active stock reservation is deleted.

Once the order is placed, the [standard stock reservation](#automatic-stock-reservation-at-order-placement) flow is honored — i.e. the manually created stock reservations not yet expired are automatically moved to `pending`, and the related stock is reserved until the order is either approved (in which case the stock quantities are decremented) or cancelled (in which case the reserved stock is released).

## Generic stock reservation

Stock reservations can also be created outside of the order scope as long as their quantity is less than or equal to the quantity of the associated stock item. Like the ones [associated with a line item](#manual-stock-reservation-before-order-placement) they get created in `draft` status, with a default expiration date of **1 hour**. Before they expire, you can move them to the `pending` status by passing the `_pending` trigger attribute.

{% hint style="info" %}
Only draft stock reservations have an expiration date [before order placement](#manual-stock-reservation-before-order-placement). Once the order is placed (or a [generic draft stock reservation](#generic-stock-reservation) is manually moved to pending) the stock is reserved until the order is approved or cancelled.
{% endhint %}

{% hint style="warning" %}
For security reasons, stock reservations can be managed using [integration](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials#integration) API credentials only.
{% endhint %}

<details>

<summary>Data model</summary>

Check the related [ER diagram](https://commercelayer.io/docs/data-model/stock-items) and explore the flowchart that illustrates how the stock reservation resource relates to the other API entities.

</details>