getProducts

Retrieve your product database.

In addition to product card fields, you can have API to return:

  • inventory quantities (set getStockInfo = 1);
  • costs and purchase prices (set getFIFOCost = 1);
  • price list prices in a particular store (set getPriceListPrices = 1);
  • recipes for assembly and bundle products (set getRecipes = 1);
  • package options (set getPackageInfo = 1);
  • replacement products (set getReplacementProducts = 1);
  • related products (set getRelatedProducts = 1);
  • product parameters (set getParameters = 1);
  • quantities of packaging materials that the product contains (set getPackagingMaterials = 1);
  • product files (manuals, specifications) (set getRelatedFiles = 1);
  • beverage containers (set getContainerInfo = 1);
  • detailed list of variations for a matrix product (set getMatrixVariations = 1).
To add or edit a product, use saveProduct. To retrieve inventory quantities ONLY, or to synchronize that data, use getProductStock. To retrieve only price list prices, use getProductPrices.

Services are also considered a special kind of products — non-stock products.

Note: PIM API offers a REST interface for retrieving products. PIM API supports more flexible filtering, for example; products can be filtered by any field, not just the predefined filters presented here.

Input parameters

Parameter name Description Possible value Required
productID Retrieve one specific product. integer
productIDs Retrieve specific products. Multiple product IDs, separated by commas, such as: 1,2,3,4,5 string
type Filter by product type. You can specify multiple product types, separated by commas (eg. "BUNDLE,ASSEMBLY").

Possible types are:
  • PRODUCT
  • BUNDLE
  • MATRIX
  • ASSEMBLY.

For a more detailed description of each type, please see below.

Please note that matrix variations (specific colors and sizes of a matrix product) are regular products; there is no separate type for those. To include or exclude matrix variations, please see the next filter: includeMatrixVariations.		 string
includeMatrixVariations This filter is for retrieving or excluding matrix variations (specific colors or sizes of a matrix product). By default, variations are included.

This filter helps you with the following two use cases:

1. If you only need to retrieve regular items and matrix parent products (NO variations), set the following filters:
  • type = "PRODUCT,BUNDLE,MATRIX,ASSEMBLY"
  • includeMatrixVariations = 0

2. If you only need to retrieve regular items and matrix variations (ie. only items you can sell; NO matrix parent products), set the following filter:
  • type = "PRODUCT,BUNDLE,ASSEMBLY"
 Integer (0 or 1),by default 1
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
groupIDsWithSubgroups Retrieve products in specific product groups, or in any of their sub-groups, sub-subgroups etc. Multiple group IDs, separated by commas, such as: 1,2,3,4,5 string
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
priorityGroupID Retrieve products in this priority group. (See getProductPriorityGroups.) integer
supplierID Retrieve products of this supplier. (See getSuppliers.) integer
brandID Retrieve products of this brand. (See getBrands.) integer
unitID Retrieve products that have this specific unit. (See getProductUnits.) integer
vatrateID Retrieve products that have this VAT / tax rate set on product card. (See getVatRates.) integer
parentProductID Retrieve only the variations of one specific matrix product. integer
code Search for a product by code, exact matches only.
For more sophisticated product search options, see input parameters findBestMatch or searchNameIncrementally.		 string
code2 Search for a product by EAN / UPC, exact matches only. string
code3 Search for a product by code 3, exact matches only. string
supplierCode Search for a product by supplier / manufacturer code, exact matches only. string
code5 Search for a product by code 5, exact matches only. "Extra product codes" module must be enabled. string
code6 Search for a product by code 6, exact matches only. "Extra product codes" module must be enabled. string
code7 Search for a product by code 7, exact matches only. "Extra product codes" module must be enabled. string
code8 Search for a product by code 8, exact matches only. "Extra product codes" module must be enabled. string
name Search for a product by name, exact matches only.
For more sophisticated product search options, see input parameters findBestMatch or searchNameIncrementally..		 string
codePrefix Search for a product by code. Returns all items where beginning of the code matches. string
code2Prefix Search for a product by EAN/UPC. Returns all items where beginning of the EAN / UPC matches. string
code3Prefix Search for a product by code 3. Returns all items where beginning of the code matches. string
supplierCodePrefix Search for a product by supplier code. Returns all items where beginning of the code matches. string
code5Prefix Search for a product by code 5. Returns all items where beginning of the code matches. "Extra product codes" module must be enabled. string
code6Prefix Search for a product by code 6. Returns all items where beginning of the code matches. "Extra product codes" module must be enabled. string
code7Prefix Search for a product by code 7. Returns all items where beginning of the code matches. "Extra product codes" module must be enabled. string
code8Prefix Search for a product by code 8. Returns all items where beginning of the code matches. "Extra product codes" module must be enabled. string
namePrefix Search for a product by name. Returns all items where beginning of the name matches. string
searchCodeFromMiddle If set to 1, and you have supplied input parameters "searchName" or "searchNameIncrementally", API will search from anywhere within the code field, not just the beginning. 0 or 1
searchName Search from product name (anywhere within the name field), product code (from the beginning), or EAN / UPC (from the beginning).
For more sophisticated product search options, see input parameters findBestMatch or searchNameIncrementally.		 string
searchNameIncrementally A more optimized product search. Specify your search phrase, and API will check whether it matches product code, EAN/UPC OR product name. It is meant for cases where API should return quickly the most relevant results, but the search does not have to be exhaustive.

API will also look for partial matches.

When using searchNameIncrementally, the results are not ordered and you cannot use paging (pageNo), nor specify how many results you want to retrieve. Pay no attention to the "recordsTotal" field - it returns a random large number!

API tries the following search combinations:
  1. Exact product code match?
  2. Exact EAN/UPC match?
  3. Product code or EAN beginning matches, or name contents match?
 string
fullTextSearchPhrase Search from product name, product code, EAN / UPC, code3, supplier code, code5, code6, code7, or code8. string
findBestMatch Set findBestMatch = 1 and send input parameters code, code2, and/or name, each of which may contain a different search phrase. API will try to find a best exact match, trying different search combinations:
  1. code, code2, name;
  2. code, code2;
  3. code2, name;
  4. code2;
  5. code, name;
  6. code;
  7. name.
This search option is useful for importing products. You may have a product code, EAN/UPC and product name (or any combination of these) — and you want a certain answer whether this exact item already exists in Erply or not.

Therefore, API will only return exact, not partial matches.

You may also use input parameter parentProductID to find a match ONLY from among the variations of a specific matrix product. This is the only additional filter which can be combined with findBestMatch = 1!		 Integer (0 or 1)
active Specify active = 0 to get archived products. (Filter status = ARCHIVED gives the same results.)

Specify active = 1 to get all non-archived products. (Filter status = ALL_EXCEPT_ARCHIVED gives the same results.)

A non-archived product can be either active, no longer ordered, or not for sale.		 0 or 1
status Filter products by status: ACTIVE, NO_LONGER_ORDERED, 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).		 string
nonStockProduct If specified, API returns only non-stock products. Salon / SPA module must be enabled. 0 or 1
isUsedProduct If specified, API returns only used products. 0 or 1
nonRefundableProduct If specified, API returns only non-refundable products. 0 or 1
hasSerialNumbers Set to 1 to retrieve only the products that have serial numbers. 0 or 1
soldInPackages 0 or 1
quickPosProducts Set to 1 to retrieve only the frequently-used products that are displayed in POS as quick-select buttons.

Each location may have different quick-select buttons. If you want the buttons for a specific store, use warehouseID input parameter. If you omit it, you will get the "default" selection.		 0 or 1
giftCards Set to 1 to retrieve only the products that are serial numbered gift cards. 0 or 1
regularGiftCards

Set this flag to 1 to retrieve only the products that are regular (non-numbered, non-serialized) gift cards.

Setting this field to 0, to omit regular gift cards and fetch everything else, does not work. Field value 0 is equivalent to not applying the filter at all.
displayedInWebshop Set to 1 to retrieve only the products that are displayed in webshop. 0 or 1
getStockInfo Set to 1 to retrieve inventory quantities for selected products.

Note that product's timestamp does not change when its inventory quantity changes. Therefore you cannot use getProducts to synchronize inventory quantities. For that purpose, see API call getProductStock instead.

Omit if not needed. Retrieving quantities takes extra resources and results are returned slower.		 0 or 1
getFIFOCost Set to 1 to retrieve FIFO costs and purchase prices for selected products.

Omit if not needed. Retrieving costs takes extra resources and results are returned slower.		 0 or 1
getContainerInfo Set to 1 to retrieve more information about the beverage container that goes with this product.

You will be needing this feature if shops are required to show beverage container as a separate item on invoice, and charge an additional fee for that.		 0 or 1
getPackageInfo Set to 1 to retrieve information about the various-sized packages for this product.

For each product that has packages, API will return an additional sub-structure named "productPackages".		 0 or 1
getReplacementProducts Set to 1 to retrieve replacement products for selected products. 0 or 1
getRelatedProducts Set to 1 to retrieve related products for selected products. If your account has configuration setting Cross-sell relationship works one way only enabled, API will not return inverse relationships. 0 or 1
getMatrixVariations Set to 1 to retrieve a detailed list of variations for a matrix product: product name, code, EAN / UPC, color and size for each variation. See output element variationList. By default (without setting getMatrixVariations = 1) you will only get the IDs of variation products. 0 or 1
getRelatedFiles Set to 1 to retrieve related files for selected products. 0 or 1
getRecipes Set to 1 to retrieve components for selected products (if selected product is a bundle or an assembly product). 0 or 1
getParameters Set to 1 to retrieve parameters for selected products. Parameters module must be enabled. 0 or 1
getPackagingMaterials Set to 1 to retrieve quantities of packaging materials for selected products. Packaging module must be enabled. 0 or 1
getPriceListPrices Set to 1 to retrieve price list prices. You can use warehouseID parameter to retrieve product's sales price for a specific warehouse. You can use clientID parameter to retrieve product's sales price for a specific customer. 0 or 1
getPriceCalculationSteps Set to 1 to retrieve a set of records detailing how price list price was received. If you specify "getPriceCalculationSteps", input parameter getPriceListPrices" is required, too. This feature requires Classic back office, version 4.5.0 or newer. 0 or 1
getItemsFromFirstPriceListOnly Set to 1 to retrieve only the products that are in first price list of a specific location. 0 or 1
getWarehouseSpecificVAT Set to 1 retrieve sales price (VAT included) that applies to specified sales location. 0 or 1
getOnlyItemsInStock Set to 1 to retrieve only the products that are in stock at specific location. 0 or 1
getProductReplacementHistory Set to 1 to retrieve list of product ids the product replaces and is replaced with. The product replacement history can be managed in the new PIM api. 0 or 1
getProductsFor

"SALES" or "ORDERING".

A filter to retrieve only sellable products, or only products that can be reordered from supplier. This filter will use product's own status, and also product's status in assortment, if an assortment has been set for the selected location.

If you specify "getProductsFor", input parameter "warehouseID" is required, too.

Cannot be used together with input parameters "active", "status", "addedSince"" and "changedSince" . (The "active" and "status" filters would conflict with the logic of "getProductsFor", and this filtered dataset is complex enough that incrementally synchronizing it is not supported.)

Behavior of this filter if no assortment has been set for the selected location:

  1. "SALES" will return "Active" and "No longer ordered" products.
  2. "ORDERING" will return "Active" and "Not for sale" products.

Behavior of the filter if the selected location has an assortment:

  1. "SALES" will return only products that are present in the assortment, and whose status BOTH on product card, and in assortment, is "Active" or "No longer ordered".
  2. "ORDERING" will return only products that are present in the assortment, and whose status BOTH on product card, and in assortment, is "Active" or "Not for sale".

To enable the assortments module on your account, please contact customer support. This feature requires Classic back office, version 4.5.0 or newer. (This filter, however, can still be used even without the assortments module.)

 string
warehouseID Specify warehouse ID to:

1) retrieve inventory quantities of selected products only in one specific warehouse. If not set, API will return inventory quantities for every warehouse. For performance reasons, it is recommended to always set this parameter if you do not need information about all warehouses simultaneously.

2) retrieve price list prices in one specific location.

3) retrieve POS quick select buttons for one specific location (quickPosProducts = 1)		 integer
clientID Customer ID (to retrieve price list prices for specified customer) integer
extraField1IDs IDs of selected values in product card extra field 1. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField1Values string
extraField2IDs IDs of selected values in product card extra field 2. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField2Values string
extraField3IDs IDs of selected values in product card extra field 3. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField3Values string
extraField4IDs IDs of selected values in product card extra field 4. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField4Values string
locationInWarehouseIDs Filter products by their "location in warehouse" ID. Multiple IDs, separated by commas. string
locationInWarehouseText Filter products by the value of their "location in warehouse" text field. Exact matches only. string
searchAttributeName Name of attribute to search from. Both "searchAttributeName" and "searchAttributeValue" have to be specified. Error 1030 will be returned if value is an array. string
searchAttributeValue Attribute value to search for. Error 1030 will be returned if value is an array. string
searchParameterOptionID Get products that have a specific parameter value.

Example: let us assume that you have defined a parameter "Available colors", with possible options of "white", "red", yellow" and "blue". Use searchParameterOptionID to get all items that are available in blue.

Of course, to make the query, you need to know the ID of the "blue" option. API call getParameters provides all parameters and their options.		 integer
searchParameterID
searchParameterValue		 Get products that have a specific parameter value.

Example 1: some product parameters are simple yes/no properties, eg. "does this product have batteries included". Assuming this parameter's ID is "456", you need to make the query searchParameterID = 456 if you want to get all products that have batteries included.

Example 2: Other parameters have scalar values, eg. the inner diameter of a ball bearing. Assuming the parameter ID is 789, you need to make the query searchParameterID = 789, searchParameterValue = "1/2" if you want to get all bearings with inner diameter of 1/2".		 Integer
String
addedSince Get all new items that have been added since a specific point in time.

NOT RECOMMENDED. Instead, use "changedSince", which returns both new items and changed items.		 Integer (Unix timestamp)
changedSince Get all items that have been ADDED AND/OR CHANGED since a specific point in time. Use this field for synchronizing product database. Set changedSince equal to the time of last successful synchronization.

Some tips:
  • Use server's timestamp, eg. the one that is returned in every response header. Your clock may be different from server clock, so if you stamp the synchronization with a locally generated timestamp, you'll risk missing some updates.

  • Product's timestamp changes when product card is updated in Erply. Timestamp DOES NOT CHANGE when product's inventory quantity changes, eg. as a result of a sale, a confirmed Purchase Invoice, or a confirmed Inventory Registration.

    If you want to synchronize inventory quantities, use API call getProductStock instead.

  • For each item that getProducts returns, check if you already have an item with that ID in your local database. If yes, update it. If not, add it as a new item.
 Integer (Unix timestamp)
lang Retrieve item names in a specific language. If omitted, API will return item names in the default language of your Erply account.
Possible values:
  • 'eng' - English
  • 'spa' - Spanish
  • 'ger' - German
  • 'swe' - Swedish
  • 'fin' - Finnish
  • 'rus' - Russian
  • 'est' - Estonian
  • 'lat' - Latvian
  • 'lit' - Lithuanian
  • 'gre' - Greek
 string
getAllLanguages Retrieve product names in all languages. If you turn on this flag, API will return additional fields nameENG, nameGER, etc. — depending on which languages have been enabled on your account. 0 or 1
orderBy 'name', 'code', 'productID', 'price', 'parentProductID', 'changed' or 'added'.

'changed' sorts by last modification timestamp. Items that have been created but never changed yet, have a modification timestamp of 0 and are sorted at the end of the list.

'added' sorts by creation timestamp.

'parentProductID', combined with orderByDir = 'asc', is useful if you need to retrieve matrix products first, followed by matrix product variations. (Matrix products have parentProductID = 0; variations have a non-zero value.)

The default value is 'changed'.		 string
orderByDir Sort direction: 'asc' (ascending order) or 'desc' (descending order). By default, items are sorted in descending order. string
recordsOnPage Number of records API should return. By default API returns 20 records.

At most you can request 1000 products at a time (or only 100, if you have set getStockInfo = 1).		 integer
pageNo API returns at most recordsOnPage items at a time. To retrieve the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1". integer
recordOffset As an alternative to pageNo, you can specify an exact list offset like in SQL. recordOffset is 0-based, so if you are retrieving items 20 at a time,
pageNo = 1 is equivalent to recordOffset = 0,
pageNo = 2 is equivalent to recordOffset = 20
and so on.		 integer
getFields Comma separated list of fields. Can be used to limit the top level fields that are returned (nested fields are not filtered). When omitted then everything will be returned.

NOTE: When using this filter with a result that does not have the set field then an empty result will be returned.		 string

Response

Field name Type Description
productID integer Product ID
type string Product type. The type can be:
  • PRODUCT - A regular item.
  • BUNDLE - A bundle product. Bundle products do not have an inventory quantity. When a bundle is sold, it is the components that are actually drawn from inventory. A bundle cannot be purchased, counted or taken into stock. The composition of a bundle product is described by its recipe. To retrieve the recipes for all bundle products, set input parameter getRecipes = 1. API then returns the field productComponents.
  • MATRIX - a matrix product. Matrix product has a number of variations - specific colors or sizes of the same design or model. The matrix product itself does not have inventory and cannot be purchased or sold. To get the list of variations for each matrix product, see the output field productVariations (which is always returned, but only contains variation IDs), or variationList (which contains more detailed information, but which you have to specifically request with getMatrixVariations = 1).
  • ASSEMBLY - An assembly product. An assembly is similar to a bundle (it has a list of components), but it is an inventory item in its own right. An assembly can be purchased as a whole, and it can also be "assembled". Assembling is a procedure that subtracts the components from inventory and takes the finished product into stock.
active integer 0 or 1. Value 0 indicates an archived product, and is equivalent to status = ARCHIVED. Archived products should not be displayed to users.

Value 1 indicates an active item. For a more detailed breakdown of active products, see the next field.
status string Product status, possible statuses are 'ACTIVE', 'NO_LONGER_ORDERED', 'NOT_FOR_SALE' and 'ARCHIVED'.
name string Product name.

Products can have different names in each language. Use input parameter lang to specify which language you want to retrieve. By default, API returns product names in account's default language.

If you want to retrieve names in all languages with one API call, set input parameter getAllLanguages = 1. In addition to field name, API will then return fields nameENG, nameGER, etc. — one for each language enabled on your account.
code string First code of the item (by convention, this is used for company's internal code)
code2 string Second code of the item (by convention, this is used for EAN/UPC barcode)
code3 string Third code of the item (note that this field may not be visible on product card by default)
supplierCode string Supplier's product code
code5 string Code 5 of the item. API only returns this field if "Extra product codes" module is enabled on your account.
code6 string Code 6 of the item. API only returns this field if "Extra product codes" module is enabled on your account.
code7 string Code 7 of the item. API only returns this field if "Extra product codes" module is enabled on your account.
code8 string Code 8 of the item. API only returns this field if "Extra product codes" module is enabled on your account.
groupID integer Product group ID
groupName string Name of the product group
price Decimal, 3 places
priceWithVat Decimal, 2 places
displayedInWebshop 0 or 1
categoryID integer
categoryName string
supplierID integer
supplierName string
unitID integer
unitName string
taxFree integer 0 or 1. If set to 1, this product is tax free in ALL stores and sales locations, regardless of POS tax rate and regardless of this product's vatrateID. (Eg. a gift card.)
deliveryTime string
vatrateID integer VAT rate (tax rate) of this item. NB! POS tax rate will override this value when selling from POS.
vatrate Decimal
hasQuickSelectButton integer 0 or 1. Value 1 indicates that this item has a quick-select button in POS.

This field is DEPRECATED, because in Erply backend you can actually define different POS quick select buttons for each shop (location, warehouse). Therefore you should use API call getPointsOfSale to retrieve POS quick buttons. For each register, API will return a quickButtons structure.

(Quick buttons are specified per-store, but getPointsOfSale returns them separately for each register.)

Please note that quick buttons may contain both services and products. We are phasing out services (new accounts do not have this module and should use non-stock products instead), but older accounts still have and use them.

If you are only interested in product buttons, you can still use API call getProducts. Set the filters quickPosProducts = 1 and warehouseID.
isGiftCard integer 0 or 1. 1 if this item is a serial numbered gift card.

If such a product is sold from POS, its serial number should be recorded and saved into the registry of sold gift cards, using API function saveGiftCard.
isRegularGiftCard integer 0 or 1. 1 if this item is a regular gift card.
nonDiscountable integer 0 or 1. 1 if this item is marked as non-discountable. Non-discountable products are related to calculateShoppingCart call. This field show only product's own flag, product can be non-discountable for card calculation if it's group, or any of group's parent group is marked as non-discountable, or if product is any type of gift card. Flag presently only applies to promotion discounts, product still can be discounted manually or using price list.
itemLevelPromotionsDisabled 1 or Null Indicates that item-level promotions are disabled for this item.
nonRefundable integer 0 or 1. 1 if this item is marked as non-refundable.
manufacturerName string
priorityGroupID integer Priority group ID. See getProductPriorityGroups.
countryOfOriginID integer Country ID. See getCountries.
brandID integer
brandName string
width integer Physical dimension. Unit depends on region, check your Erply account (typically inches or mm).
height integer Physical dimension. Unit depends on region, check your Erply account (typically inches or mm).
length integer Physical dimension. Unit depends on region, check your Erply account (typically inches or mm).
lengthInMinutes integer Length in minutes, for a salon service.
setupTimeInMinutes integer Service set-up time in minutes.
cleanupTimeInMinutes integer Service cleanup time in minutes.
walkInService integer 0 or 1.
rewardPointsNotAllowed integer 0 or 1.
nonStockProduct integer 0 or 1.
isUsedProduct integer 0 or 1, 1 if this item is a used product.
hasSerialNumbers integer 0 or 1.
soldInPackages integer 0 or 1.
cashierMustEnterPrice integer 0 or 1.

If this field is set to 1, a prompt to enter price will appear in Berlin POS (3.26 and newer) every time the item is sold. (Even if the item has a price on product card or price lists, cashier will override the price every time, so the price lists will not apply.)

This feature is used for random-weighted or random-priced items which are sold in units. (Inventory will be in units, but each unit might have a unique price given to it.)
netWeight number Item's net weight. Unit depends on region, check your Erply account (typically lbs or kg)
grossWeight number Item's gross weight (with packaging). Unit depends on region, check your Erply account (typically lbs or kg)
volume integer Item's fluid volume, eg. for beverages or perfumery. Unit depends on locale, check your Erply account (typically mL or fl oz)
description String (65535) - plain text Product description in default language, plain text.
longdesc String (65535) - HTML Longer product description in default language, HTML.
descriptionENG String (65535) - plain text Product description in English (if needed besides default language), plain text.
longdescENG String (65535) - HTML Longer product description in English (if needed besides default language), HTML.
descriptionRUS String (65535) - plain text Product description in Russian (if needed besides default language), plain text.
longdescRUS String (65535) - HTML Longer product description in Russian (if needed besides default language), HTML.
descriptionFIN String (65535) - plain text Product description in Finnish (if needed besides default language), plain text.
longdescFIN String (65535) - HTML Longer product description in Finnish (if needed besides default language), HTML.
cost number Product unit cost.

This is an informative, unchanging cost you can edit yourself on Erply's product card. To get real current costs for the batches in stock, use FIFOCost instead.
FIFOCost number Average product unit cost, for the batches currently in stock.

To retrieve this field, set getFIFOCost = 1. If you have specified warehouse ID, API returns FIFO cost of selected products in one specific warehouse. Otherwise, the cost given is an average over all warehouses. See the structure "warehouses" below to get costs for each warehouse separately.

Cost = purchase price + freight and other additional costs.
purchasePrice number Average purchase price, for the batches currently in stock.

Purchase price is basically the same as FIFO cost, but excluding freight and other additional costs.

To retrieve this field, set getFIFOCost = 1. If you have specified warehouse ID, API returns purchase price of selected products in one specific warehouse. Otherwise, the purchase price given is an average over all warehouses. See the structure "warehouses" below to get purchase prices for each warehouse separately.
backbarCharges number Amount of backbar charges for this service.
serviceDuration number Service duration in minutes.
added integer Unix timestamp. Creation time.
addedByUsername String (16) An identifier referring to the user who created this product. This is NOT actually the user's name; it's just a string, at most 16 characters long. However, typically it matches the first 16 characters of the user's name.
lastModified integer Unix timestamp. Last modification time.
lastModifiedByUsername String (16) An identifier that refers to the user who last modified this product. This is NOT actually the user's name; it's just a string, at most 16 characters long. However, typically it matches the first 16 characters of the user's name.
images array Product pictures. For each picture, Erply provides 4 URLs for 4 different image sizes. These URLs must not be hotlinked — you need to download the images to your application and serve them from there.

Access to images is currently limited and the images are not accessible by default. If you need to access the files, please contact Erply customer support.

For each image, the following information is provided:
Field nameTypeDescription
pictureIDIntegerImage ID
nameString (255)A descriptive name for the file. May be empty.
thumbURLString (255)URL of image thumbnail (by default 100 x 100 px)
smallURLString (255)URL of a small version of the image (by default 200 x 200 px)
largeURLString (255)URL of a large version of the image (by default 800 x 600 px)
fullURLString (255)URL of the full-size original image
externalInteger0 or 1. A flag that indicates whether the image is stored as a local file in Erply, or as a URL to an external location, eg. a content delivery network.
hostingProviderStringA codename for the hosting provider, if the file is stored in an external location. May be empty.

This is used only for Erply's internal purposes, eg. to know how to remove image files from a specific CDN when the picture is removed from Erply.
hashString/NULLCDN Only field. Hash filename in the cdn.
tenantString/NULLCDN Only field. Tenant in the cdn.

The same information is also available through a standalone API call getProductPictures. Use it if you need to fetch all images, or retrieve an image by ID.
warehouses Dictionary Warehouse-specific inventory quantities and/or unit costs.

To retrieve inventory quantities per warehouse, specify getStockInfo = 1. To retrieve costs, specify getFIFOCost = 1.

Keys of the array correspond to warehouse IDs. If only one warehouse was specified, the array will contain only one item. Each item has the following attributes:

warehouseID - Integer - ID of the warehouse

totalInStock - amount currently in stock

reserved - amount reserved to customers

free = totalInStock - reserved

orderPending - amount that has already been ordered from suppliers (purchase orders that have been confirmed)

reorderPoint - reorder point (if stock amount falls below that, it needs to be restocked) for this particular product, in this particular warehouse

restockLevel - restocking level (when placing purchase orders, the item is by default restocked to specified amount) for this particular product, in this particular warehouse.

FIFOCost - FIFO cost.

purchasePrice - purchase price.
variationDescription array This field describes the color and size of a matrix variation. Only matrix variations (products that are a specific color and size of a matrix product) have this field.

This array contains at most 3 elements (first, second and third dimension) and each item looks like this:

Field nameTypeDescription
nameStringname of the dimension (eg. "Size")
valueStringname of dimension's value (eg. "Medium")
orderIntegerPosition number of the dimension
dimensionIDIntegerID of the dimension (ID of "Size")
variationIDIntegerID of dimension's value (ID of "Medium")


For Berlin POS and Touch POS, this field is not returned by default, but POS can request it with a special input parameter posGetVariationDescription = 1.
productVariations array A list of the variation product IDs for this matrix product. Only matrix products (type = MATRIX) have this output field.

If you need more detailed information about each item (IDs only are not sufficient), see the next field.
variationList array Detailed information about the variations of this matrix product. Only matrix products (type = MATRIX) have this output field.

To retrieve this information, you need to set input parameter getMatrixVariations = 1.

Each item looks like this:

Field nameTypeDescription
productIDIntegerID of the variation product (ID of the product "Shirt Red L")
nameStringName of the variation (eg. "Shirt Red L")
codeStringCode of the variation (eg. "10056-Red-L")
code2StringEAN / UPC of the variation
dimensionsArrayA description of the item's color and size (ie. the "dimensions"). This array contains at most 3 elements (first, second and third dimension) and each item looks like this:

Field nameTypeDescription
nameStringname of the dimension (eg. "Size")
valueStringname of dimension's value (eg. "Medium")
codeStringcode of dimension's value (eg. "M")
orderIntegerPosition number of the dimension value (ie. what is the position of this color in the list of all colors).
dimensionIDIntegerID of the dimension (ID of "Size")
dimensionValueIDIntegerID of dimension's value (ID of "Medium")
parentProductID integer For matrix variations only: the ID of matrix parent product.
containerID integer ID of another product, a beverage container that is always sold together with this item.
containerName String (255) Name of the associated product, the beverage container. Set parameter getContainerInfo=1 to retrieve this field.
containerCode String (255) Code of the associated product, the beverage container. Set parameter getContainerInfo=1 to retrieve this field.
containerAmount string Number of beverage containers that this product contains. (Eg. if your product is "A Case of Coca-Cola", it might contain 24 cans.) Set parameter getContainerInfo=1 to retrieve this field.
packagingType string Type of packaging, possible values - "ORDINARY_PACKAGE", "METAL_BEVERAGE_PACKAGE", "RETURNABLE_PACKAGE" or empty.
packages Dictionary Deprecated - list of available product packages for this item in old format.
productPackages array List of product packages.

Information about the various-sized packages for this item (eg. a pack of 4, a crate of 20, a pallet of 500).

Each package record looks like this:

Field nameTypeDescription
packageIDIntegerPackage ID
packageTypeStringPackage type name in current language
packageTypeIDIntegerPackage type ID, full list in getProductPackageTypes
packageAmountDecimalAmount that this package contains
packageCodeStringPackage barcode
packageNetWeightDecimalPackage weight without packing materials
packageGrossWeightDecimalPackage total weight
packageLengthDecimal
packageWidthDecimal
packageHeightDecimal

To have getProducts return product parameters, set input field "getPackageInfo" to 1.

Set the "lang" parameter to retrieve package names in an appropriate language.

To add, modify or remove packages, see API calls saveProductPackage and deleteProductPackage.
replacementProducts array Replacement products for this item. This element is an array of product IDs. To retrieve this list, specify getReplacementProducts = 1.
relatedProducts array Related items.

Please note that on Erply product card, related products subsection is not visible by default. It needs to be specially enabled.

This is an array of product IDs. To retrieve this list, specify getRelatedProducts = 1.
relatedFiles array Product files (brochures, manuals, specifications). For each file, API provides a URL.

Please note that the files (as well as product images) are not accessible by default. To get access to the files, please contact Erply customer support.

For each file, the following information is provided:
Field nameTypeDescription
fileIDIntegerID of the file
nameStringA descriptive name for the file. May be empty.
typeIDIntegerFile type ID. Types are defined in Settings » Inventory settings » Product file types. See getProductFileTypes.
typeNameStringname of the file type
isInformationFileInteger(0/1)A flag for categorizing the files
fileURLStringURL of file.
externalInteger0 or 1. A flag that indicates whether the file is stored as a local file in Erply, or as a URL to an external location, eg. a content delivery network.
hostingProviderStringA codename for the hosting provider, if the file is stored in an external location. May be empty.

This is used only for Erply's internal purposes, eg. to know how to remove files from a specific CDN when the file is removed from Erply.

To retrieve this information, specify getRelatedFiles = 1.

The same information is also available through a standalone API call getProductFiles. Use it if you need to fetch all files, or retrieve a file by ID.
productComponents array Composition, or recipe, of a BUNDLE or ASSEMBLY product.

A bundle product does not have a stock quantity. When a bundle is sold, it is the components that are actually drawn from inventory.

An assembly product, on the other hand, is an inventory item in its own right. It can be purchased as a whole, but it can also be "assembled"; this is a procedure that subtracts the components from inventory and takes the finished product into stock.

Component list provides the following information:
Field nameTypeDescription
componentIDIntegerID of the component product
amountDecimalComponent amount

To retrieve this information, specify getRecipes = 1.
priceListPrice number Sales price (VAT excluded) that applies to specified sales location or customer. API returns this attribute if parameter "getPriceListPrices" is specified.
priceListPriceWithVat number Sales price (VAT included) that applies to specified sales location or customer. API returns this attribute if parameter "getPriceListPrices" is specified.
priceCalculationSteps array List of records. Each record looks like this:

Field nameTypeDescription
priceListIDIntegerPrice list ID
priceListNameStringPrice list name
priceDecimalUnit price specified in this price list
discountDecimalUnit $ discount given by this price list
typeString"PRICE" or "DISCOUNT"
percentageDecimalDiscount percentage from the price list (only present if the price list specified a percentage discount).

API returns this attribute if parameter "getPriceCalculationSteps" is specified.
locationInWarehouse string Location in warehouse. DEPRECATED — this is a merged field that contains both the "location in warehouse" classifier selected from a drop-down, and the contents of the "location in warehouse" text field. To get these values separately, see the following fields.
locationInWarehouseID integer ID of product's location in warehouse (selected from a drop-down list). To get a list of the classifiers, see getLocationsInWarehouse.
locationInWarehouseName string Name of the "location in warehouse" that the previous ID refers to.
locationInWarehouseText string Contents of the "location in warehouse" text field on product card.

There are two options for classifying products - locations in warehouse can be predefined as a list and selected from a drop-down, or entered as free text on every product card.
reorderMultiple integer
extraField1Title String (255) Title for product card extra field 1. (Users can customize field label if they want it to be named something else than "Extra Field 1"). The title is returned in specified language, or account's default language otherwise.

API outputs this field, and all the following "extraField..." fields only if "Extra product card fields" module is enabled on your account.
extraField1ID integer ID of selected value in product card extra field 1. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField1Values.
extraField1Code String (50) Code of selected value in product card extra field 1.
extraField1Name String (255) Name of selected value in product card extra field 1.
extraField2Title String (255) Title for product card extra field 2. (Users can customize field label if they want it to be named something else than "Extra Field 2"). The title is returned in specified language, or account's default language otherwise.
extraField2ID integer ID of selected value in product card extra field 2. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField2Values.
extraField2Code String (50) Code of selected value in product card extra field 2.
extraField2Name String (255) Name of selected value in product card extra field 2.
extraField3Title String (255) Title for product card extra field 3. (Users can customize field label if they want it to be named something else than "Extra Field 3"). The title is returned in specified language, or account's default language otherwise.
extraField3ID integer ID of selected value in product card extra field 3. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField3Values.
extraField3Code String (50) Code of selected value in product card extra field 3.
extraField3Name String (255) Name of selected value in product card extra field 3.
extraField4Title String (255) Title for product card extra field 4. (Users can customize field label if they want it to be named something else than "Extra Field 4"). The title is returned in specified language, or account's default language otherwise.
extraField4ID integer ID of selected value in product card extra field 4. The field on product card is a drop-down, and the possible values can be retrieved with API call getProductExtraField4Values.
extraField4Code String (50) Code of selected value in product card extra field 4.
extraField4Name String (255) Name of selected value in product card extra field 4.
salesPackageClearBrownGlass number Sales package - amount of clear/brown glass. To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackageGreenOtherGlass number Sales package - amount of green/other glass. To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackagePlasticPpPe number Sales package - amount of plastic (PP, PE). To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackagePlasticPet number Sales package - amount of plastic (PET). To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackageMetalFe number Sales package - amount of metal (Fe). To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackageMetalAl number Sales package - amount of metal (Al). To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackageOtherMetal number Sales package - amount of other metal. To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackageCardboard number Sales package - amount of cardboard. To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackageWood number Sales package - amount of wood. To retrieve this field, set input parameter getPackagingMaterials = "1".
salesPackagePaperAndCardboardMono number Sales package - paper and cardboard (mono). To retrieve this field, set input parameter getPackagingMaterials = "1".
groupPackagePaper number Group package - amount of paper. To retrieve this field, set input parameter getPackagingMaterials = "1".
groupPackagePlastic number Group package - amount of plastic. To retrieve this field, set input parameter getPackagingMaterials = "1".
groupPackageMetal number Group package - amount of metal. To retrieve this field, set input parameter getPackagingMaterials = "1".
groupPackageWood number Group package - amount of wood. To retrieve this field, set input parameter getPackagingMaterials = "1".
groupPackageFerrousMetal number Group package - amount of ferrous metal. To retrieve this field, set input parameter getPackagingMaterials = "1".
groupPackageNonFerrousMetal number Group package - amount of non-ferrous metal (incl. aluminium). To retrieve this field, set input parameter getPackagingMaterials = "1".
transportPackageWood number Transport package - amount of wood. To retrieve this field, set input parameter getPackagingMaterials = "1".
transportPackagePlastic number Transport package - amount of plastic. To retrieve this field, set input parameter getPackagingMaterials = "1".
transportPackageCardboard number Transport package - amount of cardboard. To retrieve this field, set input parameter getPackagingMaterials = "1".
transportPackageFerrousMetal number Transport package - amount of ferrous metal. To retrieve this field, set input parameter getPackagingMaterials = "1".
transportPackageNonFerrousMetal number Transport package - amount of non-ferrous metal (incl. aluminium). To retrieve this field, set input parameter getPackagingMaterials = "1".
registryNumber string The product's identification number in a state registry (eg. for alcoholic beverages).
alcoholPercentage number Percentage of alcohol by volume in the beverage.
batches string List of current batches in stock (batch identification numbers), separated by semicolons. This field is only meant to be used for specific reporting purposes (eg. for alcoholic beverages), where batches are identified by an official identification number. Erply does not manage these "batches" automatically; it only allows to associate a sales document row with a batch number.
exciseDeclaration string Number and date of the excise declaration for this product (eg. an alcoholic beverage), and other relevant information about the declaration
exciseFermentedProductUnder6 number
exciseWineOver6 number
exciseFermentedProductOver6 number
exciseIntermediateProduct number
exciseOtherAlcohol number
excisePackaging number
attributes array Additional attributes. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringAttribute value
longAttributes array Additional attributes — longer strings. Each item looks like this:

Field nameTypeDescription
attributeNameStringAttribute name
attributeValueStringAttribute value
parameters array List of parameters.

"Product parameters" is a Erply add-on module, primarily for web shops. It needs to be set up in a specific way, and is not enabled by default. If you are looking for a simple way to attach extra key-value data to products, see "Attributes" above.

To work with parameters, you first need to define "parameter groups" in Erply backend, and associate these with product groups. Each group defines parameters for a specific type of product. Eg.: inner and outer diameter for bearings; volume, energy rating and physical dimensions for refrigerators etc.

Each parameter record looks like this:

Field nameTypeDescription
parameterIDIntegerParameter ID
parameterNameStringParameter name
parameterTypeStringParameter type. Possible values: TEXT, NUMERIC, BOOLEAN, MULTIVALUE
parameterGroupIDIntegerParameter group ID
parameterValueStringParameter value. Not set for MULTIVALUE parameters.
parameterOptionsArrayOnly for MULTIVALUE parameters — shows which options from the multi-select list are enabled for this particular item.

Each item in array has the following attributes:

optionID - Integer
optionName - String
optionAdditionalPrice - Decimal.

To have getProducts return product parameters, set input field "getParameters" to 1.
productReplacementHistory array Product Replacement History.

Only returned when getProductReplacementHistory flag is used.

Shows what products replace this product and what product have been replaced by it. This list can be managed with the new PIM api.

Field nameTypeDescription
replacesIDsArrayProduct ID's that this product replaces.
replacedWithIDsArrayProduct ID's that this product is replaced with.