Real-time inventory check

Real-time Inventory Check is an optional feature where the merchant enables and provides an API endpoint to eBay, and eBay will make a call to this endpoint at checkout to verify that adequate quantity exists to fulfill the order for an inventory item. When building/enabling this endpoint, the merchant must make sure that one call can support multiple SKUs and inventory locations, and the response time should be 500 ms or less.

Request from eBay to merchant

The call from eBay to the merchant will use the HTTP POST method. The POST method should not rely on application/x-www-form-urlencode, and it should use the Content-Type and Accept request headers, with both values set to application/json. The request payload will include the following:

  • merchantLocationKey: this string is the unique identifier of the inventory location, and this identifier was created when the merchant first created the inventory location; this field is case-sensitive
  • SKU: this string is the unique identifier of the inventory item, and this identifier was created when the merchant first created the inventory item; this field is case-sensitive
  • fulfillmentType: this field takes one of the following enumeration values, based on the fulfillment type: PICKUP_IN_STORE, SHIP_TO_STORE, or SHIP_TO_HOME
  • requestedQuantity: this integer value is the purchase quantity

Below is a sample request in JSON format:

{
"locationID":"SUNNYVALE-123",
"SKU":"SKU1234",
"fulfillmentType":"SHIP_TO_HOME",
"requestedQuantity":10
}

Response from merchant to eBay

In the response, the merchant will be expected to return the following fields to eBay:

  • isAvailable: this boolean indicates whether or not adequate quantity exists for the merchant to fulfill the order
  • lastUpdated: this a UTC epoch timestamp that indicates when the last inventory check for the inventory item was performed
  • totalAvailableQuantity: this integer value indicates the currently available quantity for the inventory item

Below is a sample response in JSON format:


{
   "isAvailable": true,
   "lastUpdated": 1371091052,
   "totalAvailableQuantity":20
 }

Behavior of API when issues occur

Below are some issues that may occur when eBay makes a call to the merchant's endpoint, and how the issue will be handled:

  • API is unreachable or times out (no response returned within 500 milliseconds). If this issue occurs, the latest quantity on record with eBay is considered as the true inventory status, and checkout will be processed without the response from the merchant
  • API returns as "out of stock" or zero quantity. This response will cause eBay to block the order and notify the buyer that the item is out of stock. The eBay offer/listing will be updated with an available quantity of 0
  • API returns a quantity less than the purchase quantity (or, totalAvailableQuantity is less than requestedQuantity). Checkout is temporarily blocked, but eBay gives the buyer the option of buying up to the available quantity of the item. The available quantity of the eBay offer/listing is not updated unless the buyer chooses to purchase a lesser quantity of the item