getProductStock

Retrieve your Erply inventory — quantities on hand, reserved amounts, Reorder Points and Restock Levels, FIFO costs, and most recent purchase prices.

By default, API returns all products that have a non-zero inventory quantity in the warehouse you specified. In other words, items with a zero inventory quantity are skipped.

However, if you use input parameters "changedSince" (all quantities that have changed since last synchronization), or "getProductsWithReorderPointDefined" / "getProductsWithRestockLevelDefined", API will also return items with zero inventory quantity.

To retrieve only a list of reserved inventory quantities, see getReservedStock.

If you need to get total stock across all warehouses, then use API call syncTotalProductStock.

Input parameters

Parameter name Description Possible value Required
warehouseID When using old inventory system, then warehouseID is a required parameter.

If this parameter is omitted, then the total stock will be returned. Don't omit the warehouseID when syncing stock amounts, use API call syncTotalProductStock instead.		 integer
productID Retrieve one specific product. integer
productIDs Retrieve specific products. Multiple product IDs, separated by commas, such as: 1,2,3,4,5 string
groupID Retrieve products in this specific product group. (See getProductGroups.) integer
groupIDWithSubgroups Retrieve products in this product group, or in any of its sub-groups, sub-subgroups etc. integer
supplierID Retrieve products of this supplier. (See getSuppliers.) integer
brandID Retrieve products of this brand. (See getBrands.) integer
priorityGroupID Retrieve products in this priority group. (See getProductPriorityGroups.) integer
categoryID Retrieve products in this specific category. (See getProductCategories.) integer
categoryIDWithSubcategories Retrieve products in this category, or in any of its sub-categories, sub-sub-categories etc. integer
parentProductID Retrieve variations of this matrix product. integer
status Filter products by status: ACTIVE, NO_LONGER_ORDERED, NOT_FOR_SALE, ACTIVE_AND_NOT_FOR_SALE, ARCHIVED, or ALL_EXCEPT_ARCHIVED.

The last one returns all non-archived items (ie. items that are active, not for sale or no longer ordered).

IF you are building a Stock Replenishment Report, ACTIVE_AND_NOT_FOR_SALE is the recommended option. It returns all items that can be ordered, skipping archived products and those marked as "not ordered any more".		 string
excludeOfflineWarehouses If set to 1, then offline warehouses are not included in the result.

This parameter should be used, when warehouseID is not set.		 integer
getReorderPoints If set to 1, API also returns Reorder Points and Restock Levels for each item.

When set to 1, then warehouseID is required		 integer
getAmountReserved If set to 1, API also returns reserved amounts. integer
getSuggestedPurchasePrice If set to 1, API also returns suggested cost for each item.

For a definition of "suggested cost", see the description of the "suggestedPurchasePrice" field below.

When set to 1, then warehouseID is required		 integer
getAveragePrices If set to 1, API also returns average purchase price and average cost.

When set to 1, then warehouseID is required		 integer
getFirstPurchaseDate If set to 1, API also returns first purchase date. ISO date (yyyy-mm-dd)
getLastPurchaseDate If set to 1, API also returns most recent purchase date. ISO date (yyyy-mm-dd)
getLastSoldDate If set to 1, API also returns most recent sale date. ISO date (yyyy-mm-dd)
getProductsWithReorderPointDefined If set to 1, API returns only products with Reorder Point defined.

When set to 1, then warehouseID is required		 integer
getProductsWithRestockLevelDefined If set to 1, API returns only products with Restock Level defined.

When set to 1, then warehouseID is required		 integer
date Retrieve inventory quantities on given date. Either date or changedSince can be set, but not both at the same time. ISO date (yyyy-mm-dd)
changedSince Get only items for which the amount on hand has recently changed Unix timestamp

Response

Field name Type Description
productID integer Product ID.
amountInStock number Total amount on hand.

This includes the amounts that are reserved to specific customers: via Sales Orders, for example. If you want to get only available inventory, subtract amountReserved from amountInStock.
amountReserved number Reserved amount (eg. pending Sales Orders).

To retrieve this field, set getAmountReserved = 1.
suggestedPurchasePrice number

"Suggested cost" for the item. If you add this product to a Purchase Order, Erply will populate the "Price" field with this value.

The value is derived as follows:

  1. If the product has a supplier, and there is a "supplier price list" for that supplier, the product's price in supplier's price list is returned.
  2. Otherwise, the price on most recent purchase invoice (regardless of supplier or location) is returned.
  3. If there have not been any purchase invoices containing that product, cost from product card is returned.
  4. If no cost defined on product card, the product's cost from the most recent Inventory Registration (regardless of location) is returned.

To retrieve this field, set getSuggestedPurchasePrice = 1.
averagePurchasePrice number Weighted average purchase price, for the batches that are currently in stock. To retrieve this field, set getAveragePrices = 1.
averageCost number Weighted average cost, for the batches that are currently in stock.

Cost = purchase price + freight costs. If you multiply this field by amountInStock, you will get the total current value of your inventory.

Whenever you sell from inventory, Erply will naturally calculate cost for the specific sold items, not use this average value. Each sold item has its own cost, since it is drawn from a specific batch (according to FIFO). If you are interested in the cost of the sold item, you can use API calls:
  • getProductCostForSpecificAmount — if you need to know the cost before you create the sales document.
  • getCostOfGoodsSold — if the sale has already taken place. Returns all sold items and their costs in a specified time period.
  • getSalesDocuments — returns the total cost of all items on the invoice (field "cost"), if you specify input parameter getCOGS = 1.

To retrieve this field, set getAveragePrices = 1.
firstPurchaseDate string First purchase date. To retrieve this field, set getFirstPurchaseDate = 1. ISO date (yyyy-mm-dd)
lastPurchaseDate string Most recent purchase date. To retrieve this field, set getLastPurchaseDate = 1. ISO date (yyyy-mm-dd)
lastSoldDate string Most recent sale date. To retrieve this field, set getLastSoldDate = 1. ISO date (yyyy-mm-dd)
reorderPoint integer Reorder point. (If amount on hand drops below that point, the item should be re-stocked.)
restockLevel integer Restock level. (Suggested amount to have on hand. The item is usually re-stocked up to this quantity.)

This API call may return a lot of data (tens of thousands of records) and the output is non-pageable. If you have a large database, API may be unable to serve the request — you will get an error code or empty output. However, there is an alternative way: you may request output in CSV format.

To retrieve output as CSV, specify responseType = "CSV". API will respond you in JSON, providing a link to a CSV file::

{
  "status":
  {
    "request":"getProductStock",
    "requestUnixTime":1371221184,
    "responseStatus":"ok",
    "errorCode":0,
    "generationTime":0.10201191902161,
    "recordsTotal":1,
    "recordsInResponse":1
  },
  "records":
  [
    {"reportLink":"http:\/\/sample.erply.com\/link\/to\/file.csv"}
  ]
}


The CSV file is in "latin1" encoding. Field separator is comma. All fields, including decimal fields, are quoted.