Reserving inventory items
Learn how to place a hold on one or more inventory items.
Last updated
Learn how to place a hold on one or more inventory items.
Last updated
In Digital River coordinated fulfillments, you can use the 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 must use its unique identifier to release the hold on the products.
A call to the typically occurs late in the checkout process, after customers have finalized their carts and selected a . So, when defining a , you can retrieve data from the checkout.
You are required to send product and shipping data in the request. We also recommend you specify a unique identifier that matches the . In addition, your request can set an expiration period.
When submitting a POST/reservations
request, you should designate a unique id
. We recommend you retrieve the 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 , you can retrieve checkoutId
from the upstream order and use this value to set .
In Digital River coordinated fulfillments, you only need to to a when using the . In the, we handle releasing a reservation's hold on products.
In your request, you must pass an array of items
. These are the 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 the 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
To make a reservation, Digital River needs both the customer's ship-to address and shipping choice. This allows us to determine which warehouses, can ship the product to the customer's country using the desired shipping method.
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 Quote
Checkout
POST/reservations
currency
âž”
shippingChoice.currency
quotes[].total
âž”
shippingChoice.amount
âž”
shippingChoice.amount
quotes[].id
âž”
shippingChoice.serviceLevel
âž”
shippingChoice.serviceLevel
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.
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.
Order
in an accepted
state
POST/fulfillment-orders
checkoutId
âž”
reservationId
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.
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 and use them to set the reservation's corresponding attributes.
To set a shippingChoice
, retrieve the shippingChoice
, and then pass the values in a POST/reservations
.
Once you successfully submit a , the clock starts ticking. If the hold expires before a containing the is created, then the reservation expires, and we delete it. At that point, the inventory is released back into circulation.
When you submit a request, a 201 Created
response contains a reservation with a unique identifier.
In Digital River coordinated fulfillments that use the , the create reservation request should be configured so that its unique identifier is the same as the .
You should persist this identifier. When you , make sure you to the request. Alternatively, you can use the identifier to cancel the reservation.
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 that use the , you can release a reservation by to a 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.
In Digital River-coordinated fulfillments that use the , we send an internal request that and releases a reservation's hold on inventory.
If you properly configure a reservation identifier, it should match the . So, when you or receive an order in an accepted
state, you can retrieve checkoutId
and use that value to set reservationId
in a POST/fulfillment-orders
.
Cancelling a allows us to release the hold and make the products available for inclusion in other .
To cancel a reservation, send its unique identifier in a }
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 or fulfillment model and create a reservation during the checkout process but don't , make sure you delete the reservation.
You should also delete a reservation if you're using the and convert the checkout to an order but, for whatever reason, fail to attach the reservation to the fulfillment order.
When you submit a , if any in the request has an 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 requested products will be reserved.