How to Build an Inventory Allocation API Request

When a customer submits an order to a ROM e-commerce application the order is captured within seconds by order management. However, there is a built-in delay before the order is actually scheduled for release. This delay accommodates processes such as fraud analysis and buyer's remorse. Depending on the business requirements for these processes this delay can take up to tens of minutes. In the meantime other customer orders are being processed.

The ROM e-commerce application can reserve inventory for the order by using the inventory allocation API. This API call should be made at the beginning of the order submission process. Doing so will significantly reduce the number of orders canceled in the warehouse due to insufficient inventory.

Building an Inventory Allocation API Request

The inventory allocation API requires the following data to be supplied as part of the request message.

A globally unique reservation identifier, which is passed along in the create order request
A globally unique request identifier, which is used by ROM to make the request idempotent

For each line item, the API requires:

item ID
unique line identifier
requested quantity
shipping method
ship-to address

The figure below illustrates an inventory allocation request for a single line order.

Example inventory allocation request with one line

<?xml version="1.0" encoding="UTF-8"?>
<AllocationRequestMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
                          requestId="3fac18d6-7d65-47e9-a4fe-489042205785" (1)
                          reservationId="9c6fc61f-3783-48a6-b5e9-8b231d1a0615"> (2)
    <OrderItem itemId="12-34567890" lineId="line1"> (3)
        <Quantity>1</Quantity> (4)
        <ShipmentDetails>
            <ShippingMethod>ANY_STD</ShippingMethod> (5)
            <ShipToAddress> (6)
                <Line1>925 1st Ave</Line1>
                <City>King of Prussia</City>
                <MainDivision>PA</MainDivision>
                <CountryCode>US</CountryCode>
                <PostalCode>19406</PostalCode>
            </ShipToAddress>
        </ShipmentDetails>
    </OrderItem>
</AllocationRequestMessage>

1	Globally unique request identifier
2	Globally unique reservation identifier
3	One `OrderItem` element per line on the order. The `//@itemId` attribute specifies the Radial identifier for the item on the line. The `//@lineId` attribute is an application provided alphanumeric string which must be unique within the order.
4	The requested quantity for the order line
5	The single string shipping method registered with Radial. This is the shipping method which represents carrier and level of service pair.
6	The validated shipping address entered by the shopper.

Reservation Identifier

The reservation identifier used for the inventory allocation API call will be needed when when constructing the create order API request. For more information please see: How to Build an Order Create API Request.

Interpreting the Inventory Allocation API Response

To invoke inventory allocation API request, send a request message like the one shown above to /v1.0/stores/<your store ID>/inventory/allocations/create.xml via HTTPS POST with the following HTTP headers.

ApiKey: <your API key>ContentType: text/xml

The ROM inventory allocations API supports the following HTTP response status codes:

Status	Description	Action
200	Success	Interrogate the response payload for additional information.
400	Bad request. The API could not process the request due to either a syntax error or bad data in the provided request payload.	This is a programming time error. Interrogate the fault message in the response payload for more information. Fix the syntax or data issue in the requesting application.
500	API processing error. The API could not process the request due to a temporary internal error.	Proceed with order submission without the inventory reservation. Do not include a reservation identifier in the order create message.

Timeouts

e-commerce application should set a reasonable timeout on all ROM API calls. If an API call does not respond within the configured timeout the application should proceed as if the call returned a 500 http status.

The figure below is an example of a successful inventory allocation call for an item that has sufficient available to sell quantity. For each line the API returns the inventory quantity reserved.

Example inventory allocation response with one line.

<?xml version="1.0" encoding="UTF-8"?>
<AllocationResponseMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        reservationId="9c6fc61f-3783-48a6-b5e9-8b231d1a0615"> (1)
    <AllocationResponse lineId="line1" itemId="12-34567890">  (2)
        <AmountAllocated>1</AmountAllocated>                  (3)
    </AllocationResponse></AllocationResponseMessage>

1	Inventory reservation identifier; note this is the same value provided on the request
2	One `AllocationResponse` element per `OrderItem` element in the request. Response lines can be correlated to request lines via `//AllocationResponse/@lineId == //OrderItem/@lineId`.
3	The inventory quantity reserved for the line

When the inventory allocation API returns an error status (400 or 500) the returned payload will be a fault message. The figure below shows an example of a fault response payload resulting from a missing lineId attribute on one of the request message lines.

<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0">  (1)
   <CreateTimestamp>2016-02-29T18:07:09+00:00</CreateTimestamp> (2)
   <Code>InvalidRequestXmlException</Code>                      (3)
   <Description>cvc-complex-type.4: Attribute 'lineId' must 
appear on element 'OrderItem'.</Description> (4)
</Fault>

1	Message payload describing an API error (http status 400 or 500)
2	Timestamp describing when the error occurred on the server
3	Unique code describing the error
4	Description of the error