Stock Scenarios

In the Offer API v2, we introduced 2 new stock elements in the Get Single Offer endpoint.

  • Quantity in Stock
  • Unreserved Stock

What makes these elements different from the Stock field and how do they work?

When sending us a Stock value through the Upsert Request you are sending us your current stock. When a customer orders 1 of your offers thereafter, we will reserve this offer to prevent it to be ordered by someone else. Consequently, there is 1 less stock unreserved and the UnreservedStock is decreased by 1. Finally, when you confirm and ship the order, we will also decrease the amount of stock of the QuantityinStock element because this offer can now no longer be sold.

We have listed a few example scenarios below:

Scenario 1 – Simple item sale
Event Stock Reservation Quantity in Stock UnreservedStock What happens?
You send an update request for your offer of 10 new stock. 10 0 10 10 You sent us your current stock level. Since there are no reservations, all stock is set to 10.
A customer on the website orders 1 of your offers. 1 10 9 A customer places an order but you have not yet confirmed it. In order to prevent someone else from ordering the same item, we decreased the amount of stock that influences the buy-button by 1. This means Unreserved stock is set to 9.

Since you still have the item, we do not yet decrease QuantityinStock value.

You confirm the order and ship it by sending us a shipping confirmation. 0 9 9 You have sent us a confirmation of the fact that you have handled and shipped the order. This means there is one less item for sale so we also decrease the QuantityInStock value.
Scenario 2 – Sales on bol.com and sales on another platform
Event Stock Reservation Quantity in Stock UnreservedStock What happens?
You send an update request for your offer of 50 new stock. 50 0 50 50 You sent us your current stock level. Since there are no reservations, all stock is set to 50.
A customer on the website orders 1 of your offers. 1 50 49 A customer places an order but you have not yet confirmed it. In order to prevent someone else ordering the same item, we decreased the amount of stock the influences the buy-button by 1. This means Unreserved stock is set to 49.

Since you still have the item, we do not yet decrease QuantityinStock value.

You get 5 orders for the same product on your own website. You need to send us a new stock update. 45 1 45 44 You sent a new stock of 45. This means the QuantityinStock of total items you  have for sale for this offer is now reset to 45 as well.

Since there is still a reservation for the open order placed by the bol.com customer, your Unreserved stock is set to 44.

You confirm the order and ship it by sending us a shipping confirmation. 0 44 44 You have sent us a confirmation of the fact that you have handled and shipped the order. This means there is one less item for sale so we also decrease the QuantityInStock value, It is now also 44.
Scenario 3 – Updates gone wrong
Event Stock Reservation Quantity in Stock UnreservedStock What happens?
You send an update request for your offer of 7 new stock. 7 0 7 7 You sent us your current stock level, since there are no reservations, all stock is set to 7.
A customer on the website orders 2 of the same Offer. 2 7 5 A customer places an order but you have not yet confirmed it. In order to prevent someone else ordering the same item, we decreased the amount of stock the influences the buy-button by 2. This means Unreserved stock is set to 5.

Since you still have the item, we do not yet decrease QuantityinStock value.

You see the order and lower your stock to 5 but do not yet ship the item. 5 2 5 3 You sent a new stock of 5. This means the QuantityinStock of total items you  have for sale for this offer is now reset to 5 as well.

Since there is still a reservation of 2 for the open order placed by the bol.com customer, your Unreserved stock is set to 3.

You confirm the order and ship it by sending us a shipping confirmation. 0 3 3 You have sent us a confirmation of the fact that you have handled and shipped the order. This means there are 2 less items for sale so we also decrease the QuantityInStock value, It is now also 3.

 

Note that in this case your Remaining stock for us seems to be 3 while you might still have 5 items in stock at your shop. This is due to the fact that we only release the reservation on the order once you confirm the shipment, not when you update the stock.