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"> <!-- see NOTE1 NOTE2 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>
</InventoryDetailsRequestMessage>| NOTE1 | One //OrderItem attribute per order line. |
| NOTE2 | //OrderItem/@itemId is the Radial identifier for the item on
the line. |
| NOTE3 | //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. |
| 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. |
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:
|
|
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"> <!-- see NOTE1 -->
<DeliveryEstimate>
<DeliveryWindow> <!-- see NOTE2 -->
<From>2016-02-17T23:26:24Z</From>
<To>2016-02-22T23:26:24Z</To>
</DeliveryWindow>
<ShippingWindow> <!-- see NOTE3 -->
<From>2016-02-15T23:26:24Z</From>
<To>2016-02-15T23:26:24Z</To>
</ShippingWindow>
<CreationTime>2016-02-12T23:26:25.084Z</CreationTime> <!-- see NOTE4 -->
<Display>true</Display> <!-- see NOTE5 -->
<Message/>
</DeliveryEstimate>
<ShipFromAddress> <!-- see NOTE6 -->
<Line1>7601 Trade Port Drive</Line1>
<City>Shepherdsville</City>
<MainDivision>KY</MainDivision>
<CountryCode>US</CountryCode>
<PostalCode>40165</PostalCode>
</ShipFromAddress>
</InventoryDetail>
</InventoryDetails>
</InventoryDetailsResponseMessage>| NOTE1 | 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). |
| NOTE2 | Estimated delivery date range |
| NOTE3 | Estimated ship date range |
| NOTE4 | 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) |
| NOTE5 | Timestamp indicating when the delivery estimate was created |
| NOTE6 | 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> <!-- see NOTE1 -->
<UnavailableItem lineId="line1" itemId="12-34567890"/> <!-- see NOTE2 -->
</UnavailableItems> </InventoryDetailsResponseMessage>| NOTE1 | //UnavailableItems appears in the response if there is insufficient
available to sell quantity for any of the lines on the request. |
| NOTE2 | 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"> <!-- see NOTE1 -->
<CreateTimestamp>2016-02-13T19:43:03+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 |