How to Build an Inventory Details API Request

Your checkout flow can obtain estimated delivery date information for each line in an order by using the ROM inventory details API. This API also returns a likely ship from address for each line, which is a required input value for subsequent tax quote calls.

For more details about the ROM inventory details API please visit the Inventory API page.

Building an Inventory Details API Request

The inventory details API requires the following data for each line item in the order:

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

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

<?xml version="1.0" encoding="UTF-8"?>
<InventoryDetailsRequestMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <OrderItem itemId="12-34567890" lineId="line1"> (1)(2)(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>
</InventoryDetailsRequestMessage>

1	One `//OrderItem` attribute per order line.
2	`//OrderItem/@itemId` is the Radial identifier for the item on the line.
3	`//OrderItem/@lineId` alphanumeric line identifier string provided by the e-commerce application which must be unique within the order. This value is used to correlate response lines with request lines.
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.

Interpreting the Inventory Details API Response

To invoke inventory details API request, send a request message like that above to /v1.0/stores/<your store ID>/inventory/details/get.xml via HTTPS POST with the following HTTP headers.

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

The ROM inventory details 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 checkout as follows: Do not display an estimated delivery date Use the address of the application’s primary or default fulfillment center as the ship from address for tax quote requests

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 checkout as follows:

Do not display an estimated delivery date
Use the address of the application’s primary or default fulfillment center as the ship from address for tax quote requests

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 details call for an item that has sufficient available to sell quantity. For each line, the API returns:

an estimated delivery date
a binary display flag which indicates if this date should be displayed to the shopper.
a ship from address

<?xml version="1.0" encoding="UTF-8"?>
<InventoryDetailsResponseMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <InventoryDetails>
      <InventoryDetail lineId="line1" itemId="12-34567890"> (1)
         <DeliveryEstimate>
            <DeliveryWindow> (2)
               <From>2016-02-17T23:26:24Z</From>
               <To>2016-02-22T23:26:24Z</To>
            </DeliveryWindow>
            <ShippingWindow> (3)
               <From>2016-02-15T23:26:24Z</From>
               <To>2016-02-15T23:26:24Z</To>
            </ShippingWindow>
            <CreationTime>2016-02-12T23:26:25.084Z</CreationTime>  (4)
            <Display>true</Display> (5)
            <Message/>
         </DeliveryEstimate>
         <ShipFromAddress>  (6)
            <Line1>7601 Trade Port Drive</Line1>
            <City>Shepherdsville</City>
            <MainDivision>KY</MainDivision>
            <CountryCode>US</CountryCode>
            <PostalCode>40165</PostalCode>
         </ShipFromAddress>
      </InventoryDetail>
   </InventoryDetails>
</InventoryDetailsResponseMessage>

1	One `//InventoryDetail` element per `//OrderItem` in the request correlated by `//@lineId` value. If there is no available quantity for sale for the line the the `//InventoryDetail` element is replaced by an `//UnavailableItem` element (see below).
2	Estimated delivery date range
3	Estimated ship date range
4	Boolean flag which indicates if the e-commerce application should display the estimated shipping date for the line (true) or if it should not (false)
5	Timestamp indicating when the delivery estimate was created
6	Ship from address

If the item is out of stock when the inventory details API call is made, then the response for a line containing that item looks a bit different. Since there is no inventory available to ship the system cannot calculate a delivery estimate or a ship from address. Instead, the line containing the out of stock item appears in the unavailable items section of the response. The figure below shows an example inventory details API response for an out of stock item.

<?xml version="1.0" encoding="UTF-8"?>
<InventoryDetailsResponseMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
  <UnavailableItems> (1)
    <UnavailableItem lineId="line1" itemId="12-34567890"/> (2)
  </UnavailableItems> </InventoryDetailsResponseMessage>

1	`//UnavailableItems` appears in the response if there is insufficient available to sell quantity for any of the lines on the request.
2	One `//UnavailableItem` element per request line for which there is insufficient available to sell quantity as identified by `//@lineId` value.

If there is less inventory available for an item than the amount requested on the inventory details request then the line containing the item will appear in both sections.

<?xml version="1.0" encoding="UTF-8"?><InventoryDetailsResponseMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0">   <InventoryDetails>      <InventoryDetail lineId="line1" itemId="12-34567890">         <DeliveryEstimate>            <DeliveryWindow>               <From>2016-02-25T00:00:00Z</From>               <To>2016-03-01T00:00:00Z</To>            </DeliveryWindow>            <ShippingWindow>               <From>2016-02-23T00:00:00Z</From>               <To>2016-02-23T00:00:00Z</To>            </ShippingWindow>            <CreationTime>2016-02-13T19:29:04.390Z</CreationTime>            <Display>true</Display>            <Message/>         </DeliveryEstimate>         <ShipFromAddress>            <Line1>7601 Trade Port Drive</Line1>            <City>Shepherdsville</City>            <MainDivision>KY</MainDivision>            <CountryCode>US</CountryCode>            <PostalCode>40165</PostalCode>         </ShipFromAddress>      </InventoryDetail>   </InventoryDetails>   <UnavailableItems>      <UnavailableItem lineId="line1" itemId="12-34567890" fault="false"/>   </UnavailableItems></InventoryDetailsResponseMessage>

When the inventory details API returns an error status (400 or 500), the returned payload is 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-13T19:43:03+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