# Reserving inventory items

In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments), you can use the [Reservations API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations) to place a hold on products. Once you [submit a reservation request](#submitting-a-reservation-request), we dynamically select the optimal warehouses to ship the items from. We do this by looking at the ship to country you provide and the product's availability

Once the reservation is successfully created, you must use its [unique identifier](#unique-identifier) to [release the hold on the products](#releasing-a-reservation).

## Submitting a reservation request

A call to the [Reservations API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations) typically occurs late in the [checkout process](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts), after customers have finalized their carts and selected a [shipping quote](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-shipping-quotes#shipping-quotes). So, when defining a [`POST /reservations`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations#reservations), you can retrieve data from the [checkout](#submitting-a-reservation-request).

You are required to send [product](#product-data) and [shipping](#shipping-data) data in the request. We also recommend you specify a [unique identifier](#unique-identifier) that matches the [checkout's identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#checkout-identifier). In addition, your request can set an [expiration period](#expiration-period).

### Unique identifier

When submitting a `POST/reservations` request, you should designate a unique `id`. We recommend you retrieve the [checkout's identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#checkout-identifier) and use that value to set the reservation's `id`.

| `Checkout` |       | `POST/reservations` |
| ---------- | ----- | ------------------- |
| `id`       | **➔** | `id`                |

This is so that later in the process when you [create a fulfillment order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders#fulfillment-orders-1), you can retrieve `checkoutId` from the upstream order and use this value to set [`reservationId`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#attaching-a-reservation).

{% hint style="warning" %}
In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments), you only need to [attach a reservation identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#attaching-a-reservation) to a [create fulfillment order request](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#creating-a-fulfillment-order) when using the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model). In the[ orchestrated model](https://docs.digitalriver.com/digital-river-api/order-management/fulfillments#automated-fulfillment-model), we handle releasing a reservation's hold on products.
{% endhint %}

### Product data

In your [`POST /reservations`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations#reservations) request, you must pass an array of `items`. These are the [inventory items](https://docs.digitalriver.com/digital-river-api/product-management/skus#inventory-items) you want to place a hold on. Each element in this array needs to specify an `inventoryItemId` and the `quantity` of the item you'd like to reserve.

{% hint style="warning" %}
In the [Digital River-coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments), SKUs and inventory items form [synchronous pairs](https://docs.digitalriver.com/digital-river-api/product-management/common-attributes). So the checkout's `skuId` can be used to set the reservation's `inventoryItemId`.
{% endhint %}

| `Checkout`         |       | `POST/reservations`       |
| ------------------ | ----- | ------------------------- |
| `items[].skuId`    | **➔** | `items[].inventoryItemId` |
| `items[].quantity` | **➔** | `items[].quantity`        |

### Shipping data

To make a reservation, Digital River needs both the customer's [ship-to address](#ship-to-address) and [shipping choice](#shipping-choice). This allows us to determine which warehouses, can ship the product to the customer's country using the desired shipping method.

#### Ship to address

The `shipTo.address` represents a customer's shipping address. You're only required to provide the ship to `country`. When defining the request, you should retrieve the [checkout's ship-to values](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/providing-address-information#ship-to-address) and use them to set the reservation's corresponding attributes.

| `Checkout`                  |       | `POST/reservations`         |
| --------------------------- | ----- | --------------------------- |
| `shipTo.address.city`       | **➔** | `shipTo.address.city`       |
| `shipTo.address.postalCode` | **➔** | `shipTo.address.postalCode` |
| `shipTo.address.state`      | **➔** | `shipTo.address.state`      |
| `shipTo.address.country`    | **➔** | `shipTo.address.country`    |

#### Shipping choice

To set a [reservation's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations)`shippingChoice`, retrieve the [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)[`shippingChoice`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/shipping-choice), and then pass the values in a `POST/reservations`.

{% hint style="info" %}
The checkout's `shippingChoice` is set by using a customer's selected [shipping quote](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/using-shipping-quotes).
{% endhint %}

| `Shipping Quote` |       | `Checkout`                    |       | `POST/reservations`           |
| ---------------- | ----- | ----------------------------- | ----- | ----------------------------- |
|                  |       | `currency`                    | **➔** | `shippingChoice.currency`     |
| `quotes[].total` | **➔** | `shippingChoice.amount`       | **➔** | `shippingChoice.amount`       |
| `quotes[].id`    | **➔** | `shippingChoice.serviceLevel` | **➔** | `shippingChoice.serviceLevel` |

### Expiration period

When making a reservation request, you can tell us when you want the hold to expire. The `expiresInSeconds` value that you provide must be a positive integer.

Once you successfully submit a [`POST /reservations`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations#reservations), the clock starts ticking. If the hold expires before a [fulfillment order](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#a-fulfillment-order) containing the [attached reservation identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#attaching-a-reservation) is created, then the reservation expires, and we delete it. At that point, the inventory is [released back into circulation](#releasing-a-reservation).

{% tabs %}
{% tab title="POST/reservations " %}

```
curl --location --request POST 'http://api.digitalriver.com/reservations' \
--header 'Authorization: Bearer <API_key>' \
--header 'Content-Type: application/json' \
...
--data-raw '{
    "id": "5744204322",
    "items": [
        {
            "inventoryItemId": "9b32defe-76ff-4c95-abb8-7dd607af92d5",
            "quantity": 1,
            "allowOversell": false
        }
    ],
    "shipTo": {
        "address": {
            "city": "Minnetonka",
            "postalCode": "55129",
            "state": "MN",
            "country": "US"
        }
    },
    "shippingChoice": {
        "currency": "USD",
        "amount": 5.95,
        "serviceLevel": "SG"
    },
    "expiresInSeconds": 300
}'
```

{% endtab %}
{% endtabs %}

## Releasing a reservation

When you submit a [`POST /reservations`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations#reservations) request, a `201 Created` response contains a reservation with a unique identifier.

{% hint style="warning" %}
In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments) that use the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model), the [create reservation request](#submitting-a-reservation-request) should be configured so that its [unique identifier](#unique-identifier) is the same as the [checkout's identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#checkout-identifier).
{% endhint %}

You should persist this identifier. When you [create a fulfillment order](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#creating-a-fulfillment-order), make sure you [attach the reservation identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#attaching-a-reservation) to the request. Alternatively, you can use the identifier to [cancel the reservation](#cancelling-a-reservation).

If you don't perform one of these operations, then the products in the reservation won't be available until the [hold expires](#expiration-period). This prevents us from maintaining an accurate, up-to-date accounting of your inventory.

{% tabs %}
{% tab title="Reservation" %}

```javascript
{
    "id": "5678901234",
    "createdTime": "2018-04-25T20:36:00Z",
    "shipTo": {
        "address": {
            "city": "Minnetonka",
            "postalCode": "55129",
            "state": "MN",
            "country": "US"
      }
    },
    "shippingChoice": {
        "currency": "USD",
        "amount": 5.95,
        "serviceLevel": "SG"
    },
    "items": [
      {
        "inventoryItemId": "9234276173",
        "quantity": 1,
        "allowOversell": false
      }
    ],
    "expiresInSeconds": 300,
    "liveMode": false
}
```

{% endtab %}
{% endtabs %}

### Attaching a reservation to a fulfillment order

This operation passes the reservation's shipping, product, and expiration date to our fulfillment services, which reduces the product's inventory levels and closes the reservation. In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments) that use the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model), you can release a reservation by[ attaching its unique identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#attaching-a-reservation) to a [`POST /fulfillment-orders`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders#fulfillment-orders-1) request. This operation passes the reservation's shipping, product, and expiration date to our fulfillment services, which reduces the product's inventory levels and closes the reservation.

{% hint style="warning" %}
In [Digital River-coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments) that use the [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model), we send an internal request that [creates a fulfillment order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders-1) and releases a reservation's hold on inventory.
{% endhint %}

If you [properly configure a reservation identifier](#unique-identifier), it should match the [checkout's identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#checkout-identifier). So, when you [synchronously](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#accepted) or [asynchronously](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#listening-for-the-order-accepted-event) receive an [order](#submitting-a-reservation-request) in an `accepted` state, you can retrieve `checkoutId` and use that value to set `reservationId` in a `POST/fulfillment-orders`.

| `Order` in an `accepted` state |       | `POST/fulfillment-orders` |
| ------------------------------ | ----- | ------------------------- |
| `checkoutId`                   | **➔** | `reservationId`           |

### Cancelling a reservation

Cancelling a [reservation ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations#reservations-id)allows us to release the hold and make the products available for inclusion in other [fulfillment orders](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders).

To cancel a reservation, send its unique identifier in a [`DELETE /reservations/{id`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations#reservations-id)`}` request. This removes the hold on *all* the inventory items in that reservation. You can't remove a hold on specific items within a reservation.

If you're using the [distributed](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model) or [orchestrated](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model) fulfillment model and [create a reservation](#submitting-a-reservation-request) during the checkout process but don't [convert the checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), make sure you delete the reservation.

You should also delete a reservation if you're using the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model) and convert the checkout to an order but, for whatever reason, fail to [attach the reservation to the fulfillment order](#attaching-a-reservation-to-a-fulfillment-order).

## Handling failed reservations

When you submit a [`POST /reservations`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/reservations#reservations), if any [inventory item](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/inventory-items) in the request has an [`allowOversell` ](https://docs.digitalriver.com/digital-river-api/product-management/common-attributes#allow-oversell)value that is set to `false`, and [inventory levels](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/checking-inventory-levels) for that item are insufficient, the entire hold request will fail. In this case, none of the requested products will be reserved.

You can remedy this in one of two ways. For the items whose inventory levels are insufficient, you could either set their `allowOversell` values to `true` or remove those products from the request.