Adding or Updating an Item in the Cart
When a shopper adds an item to your shopping cart, or when the shopper increases the quantity for an item in the cart, you can do a real-time quantity check to confirm that sufficient quantity is available for the item.
Make a Quantity Check API Request
The quantity check takes a list of one or more items identified by item ID.
The figure below shows a quantity check request payload for a single item identified as 12-34567890.
<?xml version="1.0" encoding="UTF-8"?>
<QuantityRequestMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<QuantityRequest lineId="line1"
itemId="12-34567890"/> <!-- see NOTE1 NOTE2 NOTE3 -->
</QuantityRequestMessage>| NOTE1 | One //QuantityRequest element per updated line item in your cart. |
| NOTE2 | lineId is the order item line identifier provided by the e-commerce application. An alphanumeric string starting with a letter. Must be unique within the request. Used to correlate lines in the response to lines in the request. |
| NOTE3 | itemID is the Radial identifier for the item associated with the cart line. |
Line identifiers must begin with a letter: ROM supports alphanumeric strings as order item line identifiers. However these strings must begin with an alpha character. For e-commerce application frameworks which use numeric line identifiers add an alpha prefix to use as the ROM line identifier.
Interpret the Quantity Check API Response
The request is made via HTTPS POST to
/v1.0/stores/<your Store ID>/inventory/quantity/get.xml
and must include the following headers:
ApiKey: <your API key>Content-Type: text/xml
The ROM quantity 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. |
Requesting application should proceed as if the API responded with a 200 status and the response payload reported sufficient quantity for all lines in the request. |
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 response payload will include an available to sell quantity for each line in the request. Response lines can be correlated to request lines by the lineId values in each.
The figure below shows an example of the payload from a successful quantity check call.
<?xml version="1.0" encoding="UTF-8"?>
<QuantityResponseMessage xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<QuantityResponse lineId="line1"
itemId="12-34567890"> <!-- see NOTE1 NOTE2 NOTE3 -->
<Quantity>5</Quantity> <!-- see NOTE4 -->
</QuantityResponse>
</QuantityResponseMessage>| NOTE1 | One //QuantityResponse element per //QuantityRequest element in
the request. |
| NOTE2 | Use this value to correlate with lines from the request, i.e. with the
corresponding //QuantityRequest/@lineId value. |
| NOTE3 | Radial item identifier for the item associated with this line. |
| NOTE4 | The available to sell quantity for the item associated with this line. |
When the quantity check 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"> <!-- see NOTE1 -->
<CreateTimestamp>2016-02-07T18:05:37+00:00</CreateTimestamp> <!-- see NOTE2 -->
<Code>InvalidRequestXmlException</Code> <!-- see NOTE3 -->
<Description>cvc-complex-type.4: Attribute 'lineId' must
appear on element 'QuantityRequest'.</Description> <!-- see NOTE4 -->
</Fault>| NOTE1 | Message payload describing an API error (http status 400 or 500) |
| NOTE2 | Timestamp describing when the error occured on the server |
| NOTE3 | Unique code describing the error |
| NOTE4 | Description of the error |