iotoms Docs

Create a stock reservation

POST
/api/v1/inventory/reservations

Reserves stock of an item against a cart or order. Fails if the quantity exceeds on-hand stock minus existing reservations. Reservations expire after a configured time; passing a clientReservationId makes retries return the existing reservation instead of creating a duplicate.

How to use it

  1. Take the item code from List items and the cart or order id the stock is for.
  2. Send itemId, quantity, reservationType and referenceId, plus a clientReservationId so a retry returns the same reservation.
  3. The reservation is ACTIVE and reduces available stock until it expires; move it on with Hold a cart reservation for checkout or Confirm a stock reservation.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

Request Body

application/json
  1. body
itemId*string

Item code to reserve, from List items. The item must exist.

quantity*number

Quantity to set aside; must be greater than zero and no more than stock on hand minus quantities already reserved.

reservationType*string

CART for an open cart (lasts the configured cart time, 20 minutes by default) or ORDER (lasts the checkout hold time, 10 minutes by default).

Value in"CART""ORDER"
referenceId*string

Identifier of the cart or order the stock is being held for.

Formatuuid
customerId?|

Optional customer the reservation is for.

clientReservationId?|

Optional id generated by your system. Resending the same id for the same item and reference returns the existing reservation.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was handled, ERROR otherwise.

message*string

Short human-readable message describing the outcome, e.g. which record was fetched or saved.

data?

The stock reservation.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/inventory/reservations' \  -H 'Content-Type: application/json' \  -d '{  "itemId": "string",  "quantity": 0,  "reservationType": "CART",  "referenceId": "8502eb05-558d-4480-8511-c1011710b340"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "itemId": "string",    "itemName": "string",    "quantity": 0,    "reservationType": "CART",    "referenceId": "8502eb05-558d-4480-8511-c1011710b340",    "customerId": "string",    "status": "ACTIVE",    "expiresAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "releasedAt": "2019-08-24T14:15:22Z",    "releaseReason": "string",    "createdAt": "2019-08-24T14:15:22Z"  }}