How to Build an Inventory Allocation API Request

When a shopper submits an order to a ROM e-commerce application, order management captures the order within seconds. However, a built-in delay occurs 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 processed.

The ROM Inventory Allocation API can reserve inventory for the order. This API call should occur at the beginning of the order submission process, immediately after the shopper clicks Submit Order. This operation holds the inventory for an order between the time the shopper starts the submit order process and when the webstore calls EP order create.

This operation serves two purposes:

  • Prevents another shopping session from reserving the inventory while the current submit order is being processed.
  • Prevents overselling items.

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

Copy this code sample. 
<?xml version="1.0" encoding="UTF-8"?>
<AllocationRequestMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
                          requestId="3fac18d6-7d65-47e9-a4fe-489042205785" 
                          reservationId="9c6fc61f-3783-48a6-b5e9-8b231d1a0615"> 
    <!-- see NOTE1 NOTE2 --> 
    <OrderItem itemId="12-34567890" lineId="line1"> <!-- see NOTE3 --> 
        <Quantity>1</Quantity> <!-- see NOTE4 --> 
        <ShipmentDetails>
            <ShippingMethod>ANY_STD</ShippingMethod> <!-- see NOTE5 --> 
            <ShipToAddress> <!-- see NOTE6 --> 
                <Line1>925 1st Ave</Line1>
                <City>King of Prussia</City>
                <MainDivision>PA</MainDivision>
                <CountryCode>US</CountryCode>
                <PostalCode>19406</PostalCode>
            </ShipToAddress>
        </ShipmentDetails>
    </OrderItem>
</AllocationRequestMessage>
NOTE1 request ID is a globally unique request identifier
NOTE2 reservationID is a globally unique reservation identifier
NOTE3 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.
NOTE4 The requested quantity for the order line
NOTE5 The single string shipping method registered with Radial. This is the shipping method which represents carrier and level of service pair.
NOTE6 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.

Copy this code sample. 
<?xml version="1.0" encoding="UTF-8"?>
<AllocationResponseMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
        reservationId="9c6fc61f-3783-48a6-b5e9-8b231d1a0615">    <!-- see NOTE1 --> 
    <AllocationResponse lineId="line1" itemId="12-34567890">  <!-- see NOTE2 -->
        <AmountAllocated>1</AmountAllocated>            <!-- see NOTE3 -->  
    </AllocationResponse></AllocationResponseMessage>
NOTE1 Inventory reservation identifier; note this is the same value provided on the request
NOTE2 One AllocationResponse element per OrderItem element in the request. Response lines can be correlated to request lines via //AllocationResponse/@lineId == //OrderItem/@lineId.
NOTE3 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.

Copy this code sample. 
<?xml version="1.0" encoding="UTF-8"?>
<Fault xmlns="http://api.gsicommerce.com/schema/checkout/1.0"> <!-- see NOTE1 --> 
   <CreateTimestamp>2016-02-29T18:07:09+00:00</CreateTimestamp> <!-- see NOTE2 -->
   <Code>InvalidRequestXmlException</Code>         <!-- see NOTE3 -->    
   <Description>cvc-complex-type.4: Attribute 'lineId' must 
appear on element 'OrderItem'.</Description> <!-- see NOTE4 --> 
</Fault>
NOTE1 Message payload describing an API error (http status 400 or 500)
NOTE2 Timestamp describing when the error occurred on the server
NOTE3 Unique code describing the error
NOTE4 Description of the error