Create Inventory Allocations

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 the Create Order API.

This operation serves two purposes:

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

URI Summary

Operation

Action

URI Template

URI Example

Transaction Type

Unique RequestID Needed for Duplicate Detection?

Non-URI Request / Payload

Response

Create allocations

POST

/vM.m/stores/STOREID/inventory/allocations/create.xml

/v1.0/stores/ABCD/inventory/allocations/create.xml

Create an inventory reservation for one or more line items.

No

XML

200 + XML response

URI domain name: Radial recommends using the new domain at apg.radial.com. To connect to production Radial APIs, use the following form of the URL:

https://apg.radial.com/v1.0/proxyname/storecode/function

You should have received the applicable information for proxyname, storecode, and function from your Radial representative.

Note: The old domain will still be in operation until further notice from Radial. For more information on Radial API URIs, see API Requests and Responses.

Schemas

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 following code sample illustrates an inventory allocation request for a single line order.

Sample 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 The request ID is a globally unique request identifier
NOTE2 The 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
An 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 status.

The following code sample 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.

Sample 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 a 400 or 500 error status, the returned payload is a fault message. The following code sample 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

Examples

One or more standard ship items

Request XML

Copy this code sample. 

<?xml version="1.0" encoding="UTF-8"?>
<AllocationRequestMessage xmlns="http://schema.gspt.net/Inventory/3.0">
  <SourceId type="CHANNEL">TMSUS</SourceId>
  <ReservationId>TEST-RESERVATION-001</ReservationId>
  <Items>
    <OrderItem>
      . . .
    </OrderItem>
  </Items>
</AllocationRequestMessage>

Response XML

Copy this code sample. 

<?xml version="1.0" encoding="UTF-8"?>
<AllocationResponseMessage xmlns="http://schema.gspt.net/Inventory/3.0">
   <AllocationResponseList>
      <AllocationResponse>
         <ItemId>item1</ItemId>
         <WebstoreLineId>line1</WebstoreLineId>
         <AmountAllocated>0</AmountAllocated>
      </AllocationResponse>
   </AllocationResponseList>
</AllocationResponseMessage>

Multiple ISPU items

Request XML

Copy this code sample. 

<?xml version="1.0" encoding="UTF-8"?>
<AllocationRequestMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
                          reservationId="23faa211-dcfd-485e-a879-492e33f76f91"
                          requestId="unique-request-id">
  <OrderItem lineId="line1" itemId="item1">
    <Quantity>5</Quantity>
      <InStorePickupDetails>
          <StoreFrontId>10-1254</StoreFrontId>
          <StoreFrontName>Storefront Name</StoreFrontName>
          <StoreFrontAddress>
              <Line1>One Big Store Rd</Line1>
              <City>King Of Prussia</City>
              <MainDivision>PA</MainDivision>
              <CountryCode>US</CountryCode>
              <PostalCode>19406</PostalCode>
          </StoreFrontAddress>
      </InStorePickupDetails>
  </OrderItem>
  <OrderItem lineId="line2" itemId="item2">
    <Quantity>5</Quantity>
      <InStorePickupDetails>
          <StoreFrontId>10-1254</StoreFrontId>
          <StoreFrontName>Storefront Name</StoreFrontName>
          <StoreFrontAddress>
              <Line1>One Big Store Rd</Line1>
              <City>King Of Prussia</City>
              <MainDivision>PA</MainDivision>
              <CountryCode>US</CountryCode>
              <PostalCode>19406</PostalCode>
          </StoreFrontAddress>
      </InStorePickupDetails>
  </OrderItem>
  <OrderItem lineId="line3" itemId="item3">
        <Quantity>5</Quantity>
        <ShipmentDetails>
            <ShippingMethod>STANDARD</ShippingMethod>
            <ShipToAddress>
                <Line1>One Bagshot Row</Line1>
                <City>Bag End</City>
                <MainDivision>PA</MainDivision>
                <CountryCode>US</CountryCode>
                <PostalCode>19123</PostalCode>
            </ShipToAddress>
        </ShipmentDetails>
    </OrderItem>
</AllocationRequestMessage>

One standard ship item and one ISPU item

Request XML

Copy this code sample. 

<?xml version="1.0" encoding="UTF-8"?>
<AllocationRequestMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0"
                          reservationId="23faa211-dcfd-485e-a879-492e33f76f91"
                          requestId="globally-unique-request-id">
  <OrderItem lineId="line1" itemId="item1">
    <Quantity>5</Quantity>
    <ShipmentDetails>
      <ShippingMethod>STANDARD</ShippingMethod>
      <ShipToAddress>
        <Line1>One Bagshot Row</Line1>
        <City>Bag End</City>
        <MainDivision>PA</MainDivision>
        <CountryCode>US</CountryCode>
        <PostalCode>19123</PostalCode>
      </ShipToAddress>
    </ShipmentDetails>
  </OrderItem>
  <OrderItem lineId="line2" itemId="item2">
    <Quantity>5</Quantity>
    <InStorePickupDetails>
      <StoreFrontId>store1</StoreFrontId>
      <StoreFrontName>Gaffer's Tater Tots</StoreFrontName>
      <StoreFrontAddress>
        <Line1>One Bagshot Row</Line1>
        <City>Bag End</City>
        <MainDivision>PA</MainDivision>
        <CountryCode>US</CountryCode>
        <PostalCode>19123</PostalCode>
      </StoreFrontAddress>
    </InStorePickupDetails>
  </OrderItem>
</AllocationRequestMessage>