Use this API to find the item inventory, for a number of items in the Dsco Platform.

 Reference the PagedItemInventoryResult JSON Object and the ItemInventory JSON Object.

 The Find Item Inventory API documents the API's URL, it's arguments/return values and how to interact with it (GET, POST, PUT, etc.) in the Dsco Interactive Playground.

Date Search Semantics

As of 10/26/2017, the search semantics for dates on this API have changed.  Previous to this change, searching by a date used the create date or last update date of the actual object in question.  After this change, the create date/last update date used will be the date the object was replicated to its final destination within the Dsco environment.  The replicated create date/last update will be very close to the actual create date/last update.  The replicated create date/last update will be used in searching to prevent a race condition where objects could be "dropped" between searches.

 Input Params

The Find Item Inventory API documents the exact fields that may be passed in on the API.  When searching, you must provide either itemId, sku, partnerSku, upc, ean, mpn, isbn, gtin, assortmentId, or exactly one of the period-based filters (itemsCreatedInLast, itemsUpdatedInLast, itemsCreatedSince, itemsUpdatedSince). 

Early May 2018 Changes

This API was re-written from the ground up to increase its performance and provide linear response times no matter what page of results is returned when using fastMode.   Note that support for the non-fastMode will go away in early 2019.

The following details the changes in the re-write for fastMode...

  • Result size
    Each page of results may contain up to 1000 objects whereas before it was between 100 and 250.
  • lastId
    This attribute continues to contain the page identifier to pass in on subsequent requests, however note that if you don't request the next page of results within 5 minutes, the request will fail and you will have to start your search over again.
  • scrollId
    Underneath the covers, this search is now backed by elastic search which uses a string for its next page identifier.  To maintain backward compatibility, Dsco is mapping this scrollId to an integer and returning it to you in lastId.  However, each time you do a search, Dsco will return to you both the lastId and the scrollId.  If you pass in a scrollId, Dsco doesn't have to pay the price to map from the integer lastId to the underlying scrollId.  At some point in 2019, lastId will go away and you will have to pass us scrollId to get the next page of results.  It works the same way as lastId, if you don't request the next page of results within 5 minutes, the request will fail and you will have to start your search over again.
  • compress
    Pass this attribute in to compress the results.  As of Early May 2018, 1000 results are returned with each request, so it is recommended that you use this attribute.
  • omitItemsOnHold
    This is true by default and may change the results in a possibly non-backward compatible way.
  • clearQuantityForStoppedItems
    This is true by default and may change the results in a possibly non-backward compatible way.
  • deprecated attributes
    These deprecated attributes will continue to work until early 2019, after which they will be removed...
    • lastId, pageNum, pageSize, pageCount

API Details

The API includes a fastMode attribute (defaults to true) to enable retrieving data in a more performant manner with large datasets.  

When fastMode is true...

  1. The PagedItemInventoryResult object returned from calls to this API will return 0 for the pageNum and pageCount attributes which should be ignored
  2. The pageNumber request attribute will be ignored
  3. Most queries will execute dramatically faster for accounts with very large datasets (especially retailers with many associated partner supplier accounts)
  4. DEPRECATED.  Please use scrollId going forward... Each API call will return a lastId attribute in the PagedItemInventoryResult object which should be passed in as the next API call's lastId request attribute in order to retrieve the next page
  5. The API will return a scrollId that should be passed in on subsequent requests to get the next page of results
  6. The final page of results will be an empty array indicating there are no more results

NOTE: the non-fastMode approach is deprectated and at some point in the future, the non-fastMode approach will be removed (the use of pageNumber to progress through pages of results) and will be removed in early 2019.

 Below you will find additional detail on the input params.

  • scrollId
    Pass this in to specify the next page of results to return.  Use this in lieu of fastMode, lastId and pageNumber.  If you don't request the next page of results within 5 minutes, the request will fail and you will have to start your search over again.
  • lastId - DEPRECATED 
    You may pass this in instead of scrollId and we will map this value from to the actual scrollId for you to maintain backward compatibility.  This attribute is deprecated and will be removed sometime in 2019.
  • omitItemsOnHold
    Only works with fastMode... If the account calling the API is a retailer, don't include items associated with a supplier when the supplier is on hold (is in on-boarding) - defaults to true.
  • clearQuantityForStoppedItems
    If the account calling the API is a retailer, set the availableQuantity to 0 and the status to out-of-stock for all items associated with suppliers that are currently stopped - defaults to true.
  • compress
    Only works with fastMode... If true, a base64 encoded string of the GZip compressed itemInventory results will be put into the resulting  PagedItemInventoryResult JSON Object  in the base64EncodedCompressedItemInventory attribute and the itemInventory attribute will note be set or will be null.  So, first decode this base64 string into a byte array and then decompress it using the gzip algorithm.  The result will be an array of ItemInventory objects.  There are examples on decoding/decompressing this attribute on the  PagedItemInventoryResult JSON Object .
  • fastMode
    When true (defaults to false), uses elastic search for searching  (see Early May 2018 above) and pageNumber will be ignored and scrollId/lastId should be used
  • pageNumber - DEPRECATED 
    This will only work when fastMode is false and this attribute will be removed in early 2019.  Use this param to specify which page of results is desired.  Initially, call this API with the pageNumber set to 1.  The response will include the total number of pages of results as the pageCount field, allowing the developer to make additional calls to this API to retrieve all pages of results.  Please note, every call to this API returns the pageCount field in the returned object and the developer should verify that the pageCount does not change as he iterates through the pages.  The pageCount would only change if the number of items is changing in the Dsco database as a result of an integration or process importing new items.  If the pageCount does change the developer should do one of the following...
    1. Enter an error condition and schedule the process to execute again at some point in the future
    2. Wait a period of time, perhaps 30 minutes, and execute the process again without creating an error condition.
  • dscoItemId
    Find the item inventory for just the item uniquely identified by this dscoItemId.
  • sku
    Find the item inventory for just the item uniquely identified by this sku.
  • partnerSku
    Find the item inventory for just the item uniquely identified by this partnerSku.  Note that if the requestor is a supplier, then either dscoRetailerId or dscoTradingPartnerId is required to identify the retailer the partnerSku is associated with.
  • upc
    Find the item inventory for just the item uniquely identified by this upc.
  • ean
    Find the item inventory for just the item uniquely identified by this ean.
  • mpn
    Find the item inventory for just the item uniquely identified by this mpn.
  • isbn
    Find the item inventory for just the item uniquely identified by this isbn.
  • gtin
    Find the item inventory for just the item uniquely identified by this gtin.
  • dscoRetailerId
    This will only be used if partnerSku is provided and the requestor is a supplier, otherwise it will be ignored.  When partnerSku is provided and requestor is a supplier either dscoRetailerId or dscoTradingPartnerId is required to identify the retailer the partnerSku is associated with.
  • dscoTradingPartnerId
    This will only be used if partnerSku is provided and the requestor is a supplier, otherwise it will be ignored.  When partnerSku is provided and the requestor is a supplier either dscoRetailerId or dscoTradingPartnerId is required to identify the retailer the partnerSku is associated with.
  • dscoSupplierId
    This attribute is supported when using fastMode only. Restricts results to just items associated with this supplier.  This attribute is ignored if the partner making the API call is a supplier.
  • dscoSupplierTradingPartnerId
    This attribute is supported when using fastMode only. Restricts results to just items associated with this supplier trading partner.  This attribute is ignored if the partner making the API call is a supplier.
  • assortmentId
    Find item inventory only in the specified assortment.  This param may not be used with any of the period-based filters below.
  • itemsCreatedInLast
    Find item inventory where the item(s) were created within the last xyz seconds.  The maximum value allowed is one year ago (31536000). This value is inclusive in that the search looks for objects greater than or equal to the time specified.
  • itemsUpdatedInLast
    Find item inventory where the item(s) were updated within the last xyz seconds.  The maximum value allowed is one year ago (31536000). This value is inclusive in that the search looks for objects greater than or equal to the time specified.
  • itemsCreatedSince
    Find item inventory where the item(s) were created since this ISO 8601 date (e.g. 2014-01-01T10:30:00+01:00). This value is inclusive in that the search looks for objects greater than or equal to the time specified.
  • itemsUpdatedSince
    Find item inventory where the item(s) were updated since this ISO 8601 date (e.g. 2014-01-01T10:30:00+01:00). This value is inclusive in that the search looks for objects greater than or equal to the time specified.
  • until
    Find items created/updated up until this ISO 8601 date (e.g. 2014-01-01T10:30:00+01:00). This param will be ignored unless one of the period-based params is included (itemsCreatedInLast, itesmUpdatedInLast, itemsCreatedSince, itemsUpdatedSince). This value is exclusive in that the search looks for objects right up to but not including the very moment requested, e.g. searching until 10:30:00 finds objects up until 10:29:59.999)

 Output Object

The result of calling this API is the PagedItemInventoryResult JSON Object. It will contain the list of ItemInventory JSON Objects returned from this API for the specified page of results if any.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.