Intershop API Documentation / Intershop Order Management REST API / Reference - IOM REST API - Reservation

IOM REST API - Create Stock Reservation

Document Properties

Kbid

2778D5

Added to KB

20-Jul-2016

Status

online

Product

IOM 1
IOM 3
IOM 5

Last Modified

11-Jan-2023

Public Access

everyone

Doc Type

References

Product

IOM 2
IOM 4

Document Link

https://knowledge.intershop.com/kb/2778D5

Share Link

Share this document

Create Stock Reservation

URI	servlets/services/reservation/<shopId>
Http Method	POST
Short Description	Create a stock reservation.
Example Requests URL	http://10.17.0.245:8080/servlets/services/reservation/10010
Example Requests	{ "lifetime": 180, "type": "COMPLETE", "items": [ { "id": "First-Test", "qty": "2" } ] }
HTTP Status Codes	201 Created 400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error
Description	This service creates stock reservations for a given OMS shop instance. A stock reservation is a list of reserved products with the appropriate amount. Each stock reservation has a validity which can be set by the field `lifetime` at the request payload. The response provides a status code 201 on success with the reserved products, the state of the reservation and a unique reservation reference ID. This service only supports and accepts requests with content-type application/json.
Parameters	Path parameter `shopId` = ID of the OMS shop instance - Example = 10010

Authorization

IOM supports "basic http authentication" only. Please configure your clients to use this authentication method. A very simple method to send REST requests on the command line can be realized using wget. The example also shows, how to configure this client to use "basic http authentication" (--auth-no-challenge).

wget -q -O- --auth-no-challenge  --http-user=<user> --http-password='<password>' \
--method=post --post-data='{"lifetime":180, "type":"COMPLETE", "items":[{"id":"First-Test", "qty":"2"}]}' \
http://<hostname>/servlets/services/reservation/10010

It is Important that the permission REST_RESERVATION (oms.RightDefDO with ID = 124 and name "Reservation REST service") is assigned to the requesting user. The permission is a part of the class bakery.persistence.dataobject.configuration.common.RightDefDO.

The user also needs the permission for the OMS shop instance which relates to the requested stock reservation.

Concurrency

To avoid overbooking of products the OMS checks the current inventory of the product before storing the reservation. The inventory check itself depends on stock reservations. For this reason the OMS uses database advisory locks to serialize the requests.

If it is not possible for a request to obtain all locks for the products to reverse within five seconds, the client gets a response with HTTP status code 500 and the following payload:

JSON

Request data format

application/json

Request related java object

bakery.v2.reservation.ReservationRequestImpl

Request Attributes

Attribute

Description

Type

Nullable

lifetime

The lifetime / validity of the stock reservation in seconds.Max value is 2147483647.
Greater values creates a response with HTTP status code 400 caused by a JsonParseException,

Default is 10 minutes.

Integer

true

type

The reservation type:

COMPLETE = products are only reserved if all products of the request are reservable
PARTLY = products are reserved, even when one or more of the reserved products are not reservable

If type is missing the OMS uses COMPLETE. All values unequal COMPLETE be interpreted as PARTLY.

String

true

items

1..n products to reserve. For details see table below.

Array

false

Item Attribute	Description	Type	Size	Nullable
id	The ID of the product. Via the OMS configurations it is determined if it is the shop or oms product ID.	String	30	false
qty	Quantity to reserve	Integer		false

Request data example

Response data format

application/json

Response related java object

bakery.webservice.rest.v1.HttpResponse

bakery.reservation.v2.ReservationResponse as "data" object

Response Attributes

Attributes	Description
data	see table below
statusCode	HTTP status code
errors	empty in case of successful processing. For details see Response Attribute Errors
exceptions	empty in case of successful processing. For details see Response Attribute Exceptions

Data Attributes	Description
validUntil	The Validity of the Stock Reservation
resvId	The id <primary key> of the Stock Reservation
items	1..n items. See table below

Item Attributes	Description
id	The ID of the product. Via the OMS configurations it is determined if it is the shop product number or the oms product ID.
qty	Reserved quantity
state	State of the reservation. The reservation of the product is still "revered" or "expired".

Response AttributeErrors

Source Field	Message
items.qty	Cannot construct instance of int from String value 'value from request': not a valid Integer value

HTTP status code= 400

Response AttributeExceptions

Code	Description
JsonParseException	For each not well formed JSON request payload
CODE_21001	The product to be reserved was not found
CODE_21003	We don't have enough stock for requested product

HTTP status code= 400

Response data example

{
  "data": {
    "validUntil": "2016-01-07 15:03:36",
    "resvId": 119,
    "items": [
      {
        "id": "First-Test",
        "qty": 2,
        "state": "reserved"
      }
    ]
  },
  "statusCode": 201,
  "errors": [
  ],
  "exceptions": [
  ]
}

Response Code

201

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Website, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.