Reserving inventory items

Learn how to place a hold on one or more inventory items.

In Digital River coordinated fulfillments, you can use the Reservations API to place a hold on products. Once you submit 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'll need to use its unique identifier to release the hold on the products.

Submitting a reservation request

A call to the Reservations API typically occurs late in the checkout process, after customers have finalized their carts and selected a shipping quote. So, when defining a POST/reservations, you can retrieve data from the checkout.

In the request, you're required to send product and shipping data. We also recommend you specify a unique identifier that matches the checkout's identifier. In addition, your request can set an expiration period.

Unique identifier

When submitting a POST/reservations request, you should designate a unique id. We recommend you retrieve the checkout's 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, you can retrieve checkoutId from the upstream order and use this value to set reservationId.

In Digital River coordinated fulfillments, you only need to attach a reservation identifier to a create fulfillment order request when you're using the distributed model. In the orchestrated model, we handle releasing a reservation's hold on products.

Product data

In your POST/reservations request, you must pass an array of items. These are the 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.

In Digital River coordinated fulfillments, SKUs and inventory items form synchronous pairs. So the checkout's skuId can be used to set the reservation's inventoryItemId.

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 and shipping choice. This allows us to determine which warehouses, if any, 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 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 shippingChoice, retrieve the checkout's shippingChoice, and then pass the values in a POST/reservations.

The checkout's shippingChoice is set by using a customer's selected shipping quote.

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, the clock starts ticking. If the hold expires before a fulfillment order containing the attached reservation identifier is created, then the reservation expires, and we delete it. At that point, the inventory is released back into circulation.

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
}'

Releasing a reservation

When you submit a POST/reservations request, a 201 Created response contains a reservation with a unique identifier.

In Digital River coordinated fulfillments that use the distributed model, the create reservation request should be configured so that its unique identifier is the same as the checkout's identifier.

You should persist this identifier. When you create a fulfillment order, make sure you attach the reservation identifier to the request. Alternatively, you can use the identifier to cancel the reservation.

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

Reservation

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

Attaching a reservation to a fulfillment order

In Digital River coordinated fulfillments that use the distributed model, you can release a reservation by attaching its unique identifier to a POST/fulfillment-orders request. This operation passes the reservation's shipping, product, and expiration date to our fulfillment services who reduce the product's inventory levels and close the reservation.

In Digital River coordinated fulfillments that use the orchestrated model, we send an internal request that creates a fulfillment order and releases a reservation's hold on inventory.

If you properly configure a reservation identifier, it should match the checkout's identifier. So, when you synchronously or asynchronously receive an order 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 allows us to release the hold and make the products available for inclusion in other fulfillment orders.

To cancel a reservation, send its unique identifier in a DELETE/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 either the distributed or orchestrated fulfillment model, and you create a reservation during the checkout process but don't convert the checkout to an order, then make sure you delete the reservation.

You should also delete a reservation if you're using the distributed model and you convert the checkout to an order but, for whatever reason, fail to attach the reservation to the fulfillment order.

Handling failed reservations

When you submit a POST/reservations, if any inventory item in the request has an allowOversell value that is set to false, and inventory levels for that item are insufficient, the entire hold request will fail. In this case, none of the products in the request 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.