saveProduct

Create or update a product.

Note: PIM API offers a REST interface for creating products.

Input parameters

Parameter name Description Possible value Required
productID Product ID if you need to change existing product integer
type Product type, possible types are 'PRODUCT', 'BUNDLE', 'MATRIX', 'ASSEMBLY'. By default 'PRODUCT'.
When updating an existing product, API will leave product type unchanged.
string
groupID ID of product group. To get the list of product groups, use getProductGroups. integer yes
unitID ID of product unit. To get the list of units, use getProductUnits. integer
brandID ID of product brand. To get the list of brands, use getBrands. integer
supplierID Supplier ID integer
vatrateID ID of VAT (tax) rate. To get the list of rates, use getVatRates. If omitted, system will apply the default rate. Note that when the item is sold, POS tax rate, if set, will override this. integer
taxFree 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.) 0 or 1
code Product's code. Must be UNIQUE, unless the account is configured otherwise. String (50)
code2 Product's second code (by convention, EAN barcode). Must be UNIQUE, unless the account is configured otherwise. String (50)
code3 Third code of the item (note that this field may not be visible on product card by default). String (50)
supplierCode Supplier's product code String (50)
code5 Code 5 of the item. "Extra product codes" module must be enabled. String (50)
code6 Code 6 of the item. "Extra product codes" module must be enabled. String (50)
code7 Code 7 of the item. "Extra product codes" module must be enabled. String (50)
code8 Code 8 of the item. "Extra product codes" module must be enabled. String (50)
active If set to 1, this item is the active product. 0 or 1
status Product status, possible statuses are 'ACTIVE', 'NO_LONGER_ORDERED', 'NOT_FOR_SALE' and 'ARCHIVED'. By default 'ACTIVE'. string
displayedInWebshop If set to 1, this item is displayed in webshop. 0 or 1
name Product name. Use either general parameter "name" or one or more of the following parameters if you need to set the names in specific languages. String (255)
nameENG String (255)
nameSPA String (255)
nameGER String (255)
nameSWE String (255)
nameFIN String (255)
nameRUS String (255)
nameEST String (255)
nameLAT String (255)
nameLIT String (255)
nameGRE String (255)
description

Product description. ("Shorter" description, plain text.)

Field size depends on account. On newer accounts, the length of this field is 65,535 characters; on older accounts, it may be 2,000 characters. (The field can be resized upon request.)

string
descriptionEST

By default, description can be entered in one language only — unlike product name, which can be specified in all languages activated on the account.

By default, you can therefore only use the "description" field.

Upon request, customer support can activate at most three more description fields, for three languages. (If your account default language, for example, is English, then the English description must be stored in field "description" and field "descriptionENG" cannot be used.)

Field size depends on account. On newer accounts, the length of this field is 65,535 characters; on older accounts, it may be 2,000 characters. (The field can be resized upon request.)

string
descriptionENG See above. string
descriptionRUS See above. string
descriptionFIN See above. string
longdesc

Longer description of the product. This is typically formatted in HTML, because Erply back office provides an HTML editor for modifying this field.

Field size depends on account. On newer accounts, the length of this field is 65,535 characters; on older accounts, it may be 4,000 characters. (The field can be resized upon request.)

string
longdescEST

By default, long description can be entered in one language only — unlike product name, which can be specified in all languages activated on the account.

By default, you can therefore only use the "longdesc" field.

Upon request, customer support can activate at most three more long description fields, for three languages. (If your account default language, for example, is English, then the English long description must be stored in field "longdesc" and field "longdescENG" cannot be used.)

Field size depends on account. On newer accounts, the length of this field is 65,535 characters; on older accounts, it may be 4,000 characters. (The field can be resized upon request.)

string
longdescENG See above. string
longdescRUS See above. string
longdescFIN See above. string
length Item's physical dimensions. Unit depends on region, check your Erply account (typically inches or mm). integer
width integer
height integer
netWeight Item's net weight. Unit depends on region, check your Erply account (typically lbs or kg). Decimal
grossWeight Item's gross weight (with packaging). Unit depends on region, check your Erply account (typically lbs or kg). Decimal
volume Item's fluid volume, eg. for beverages or perfumery. Unit depends on locale, check your Erply account (typically mL or fl oz). integer
netPrice Default sales price of the product, excluding VAT. Decimal
priceWithVAT

Default sales price of the product, VAT included.

"netPrice" and "priceWithVat" do not have to be specified both - set one of them and API will calculate the other.

Decimal
hasQuickSelectButton Set the value to 1 if you want the product to have a quick-select button in POS integer
isGiftCard Set the value to 1 if this product 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 call saveGiftCard.
integer
isRegularGiftCard Set the value to 1 if this product is a regular gift card. 0 or 1
nonDiscountable Set the value to 1 if this item must be non-discountable. Flag presently only applies to promotion discounts, product still can be discounted manually or using price list. 0 or 1
itemLevelPromotionsDisabled Set the value to 1 if item-level promotions are disabled for this item. 0 or 1
nonRefundable Set the value to 1 if this item must be non-refundable. 0 or 1
lengthInMinutes Default length for the service in minutes. integer
setupTimeInMinutes Service set-up time in minutes. integer
cleanupTimeInMinutes Service cleanup time in minutes. integer
rewardPointsNotAllowed Set the value to 1 if this product does not grant customer reward points. 0 or 1
cost Product cost Decimal
manufacturerName String (255)
categoryID integer
priorityGroupID integer
countryOfOriginID integer
containerID ID of another product, a beverage container that is always sold together with this item. integer
containerAmount Number of beverage containers that this product contains. (Eg. if your product is "A Case of Coca-Cola", it might contain 24 cans.) integer
deliveryTime String (255)
backbarCharges Amount of backbar charges for this service. Decimal
serviceDuration Service duration in minutes. Decimal
labelsNotNeeded If set to 1, this product does not need printed labels. 0 or 1
nonStockProduct Set the value to 1 if this item is a non-stock product. 0 or 1
isUsedProduct Set the value to 1 if this item is a used product. 0 or 1
cashierMustEnterPrice

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 can be 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.)

0 or 1
walkInService (For Salon customers.) Set the value to 1 if this item is a service that walk-in customers can themselves select in the Walk-In View, and register for an appointment. 0 or 1
packagingType Type of packaging, allowed values - "ORDINARY_PACKAGE", "METAL_BEVERAGE_PACKAGE" or "RETURNABLE_PACKAGE" string
extraField1ID 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. integer
extraField2ID 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. integer
extraField3ID 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. integer
extraField4ID 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. integer
reorderMultiple integer
reorderPoint# Reorder point. (If amount on hand drops below that point, the item should be re-stocked.)

Reorder point has to be defined for a specific warehouse / location. Replace # with warehouse ID, eg. reorderPoint1 for warehouse with ID = 1.
Decimal
restockLevel# Restock level. (Suggested amount to have on hand. The item is usually re-stocked up to this quantity.)

Restock level has to be defined for a specific warehouse / location. Replace # with warehouse ID, eg. restockLevel1 for warehouse with ID = 1.
Decimal
replacementProductIDs Replacement product IDs, separated by commas, such as: 1,2,3,4,5 string
relatedProductIDs Related product IDs, separated by commas, such as: 1,2,3,4,5 string
parentProductID Parent product ID. Only for matrix variations (specific colors/sizes of a matrix item). See guidelines below. integer
locationInWarehouseID ID of selected location in warehouse. integer
locationInWarehouseText Product's specific text added to location in warehouse. String (255)
dimensionID# Matrix product dimension ID. Only for matrix products. See guidelines below. integer
dimValueID# Dimension Value ID. Only for matrix variations. See guidelines below. integer
Guidelines for creating matrix products

Matrix items have 1...3 dimensions - color, size etc. Matrix dimensions can be defined in Erply backend (in Settings » Matrix Dimensions) or with API call saveMatrixDimension.

A dimension has a name (eg. "Letter Sizes" or Spring 2013 Colors") and a list of possible values (eg. S, M, L or Lime, Yellow, Fuchsia). API call getMatrixDimensions returns a list of all dimensions you have defined.

To create a matrix product, first pick the dimension(s) that apply to this particular product, eg "Waist Size" and "Length" for jeans. A matrix can have up to 3 dimensions.

  1. Create the parent product (matrix product). You will not be selling this item directly, but Erply needs this item to group all sizes/colors together. Set:
    • type = MATRIX
    • dimensionID1 = first dimension ID
    • dimensionID2 = second dimension ID (if needed)
    • dimensionID3 = third dimension ID (if needed)

  2. Create the specific variations (color/size combinations), each one as a separate product. Set:
    • type = PRODUCT
    • parentProductID = ID of the matrix item
    • dimValueID1, dimValueID2, dimValueID3 as needed (corresponding to how many dimensions the matrix has.)

***** Quantities of packaging materials.
salesPackageClearBrownGlass Sales package - amount of clear/brown glass. Decimal
salesPackageGreenOtherGlass Sales package - amount of green/other glass. Decimal
salesPackagePlasticPpPe Sales package - amount of plastic (PP, PE). Decimal
salesPackagePlasticPet Sales package - amount of plastic (PET). Decimal
salesPackageMetalFe Sales package - amount of metal (Fe). Decimal
salesPackageMetalAl Sales package - amount of metal (Al). Decimal
salesPackageOtherMetal Sales package - amount of other metal. Decimal
salesPackageCardboard Sales package - amount of cardboard. Decimal
salesPackageWood Sales package - amount of wood. Decimal
salesPackagePaperAndCardboardMono Sales package - paper and cardboard (mono). Decimal
groupPackagePaper Group package - amount of paper. Decimal
groupPackagePlastic Group package - amount of plastic. Decimal
groupPackageMetal Group package - amount of metal. Decimal
groupPackageWood Group package - amount of wood. Decimal
groupPackageFerrousMetal Group package - amount of ferrous metal. Decimal
groupPackageNonFerrousMetal Group package - amount of non-ferrous metal (incl. aluminium). Decimal
transportPackageWood Transport package - amount of wood. Decimal
transportPackagePlastic Transport package - amount of plastic. Decimal
transportPackageCardboard Transport package - amount of cardboard. Decimal
transportPackageFerrousMetal Transport package - amount of ferrous metal. Decimal
transportPackageNonFerrousMetal Transport package - amount of non-ferrous metal (incl. aluminium). Decimal
***** Alcohol details. Alcohol wholesale module must be enabled.
registryNumber The product's identification number in a state registry (eg. for alcoholic beverages). String (255)
alcoholPercentage Percentage of alcohol by volume in the beverage. Decimal
batches 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. String (255)
exciseDeclaration Number and date of the excise declaration for this product (eg. an alcoholic beverage), and other relevant information about the declaration String (255)
exciseFermentedProductUnder6 Decimal
exciseWineOver6 Decimal
exciseFermentedProductOver6 Decimal
exciseIntermediateProduct Decimal
exciseOtherAlcohol Decimal
excisePackaging Decimal
***** Additional attributes associated with this item.
Attributes must be supplied as a flat list, each attribute defined by the following set of three parameters. Replace # with set number (1, 2, 3, ...). When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'.
attributeName# Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore. String (50)
attributeType# Attribute type, possible types are 'text', 'int' and 'double'. By default 'text'. string
attributeValue# Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute.
'text' attribute can be any string, maximum 255 characters.
'int' must be a signed 32-bit integer.
'double' must be a decimal number.
string
***** To store strings longer than 255 characters, use "long attributes". (All accounts might not have this capability (API returns error 1006). If necessary, please ask Erply customer support to turn this feature on.)

As with regular attributes, send parameters longAttributeName1 and longAttributeValue1 to store an attribute, longAttributeName2 and longAttributeValue2 to store another etc. The "#" symbol below should be replaced with numbers 1, 2, 3, etc.

When updating an existing entry, API will only update the attributes specified in input data and leave all other existing attributes unchanged. To delete an attribute, set its value to 'null' or 'undefined'.
*****
longAttributeName# Attribute name. Name can only contain the following symbols: A-Z, a-z, 0-9, dash and underscore. String (50)
longAttributeValue# Value of the attribute. Set value to 'null' or 'undefined' to delete an attribute. String (65,535)
***** Custom 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 parameter 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.

For each parameter that you want to change, send its ID and new value. For the first parameter, parameters should be named parameterID1 and parameterValue1; for the second one, parameterID2 and parameterValue2 etc.
parameterID# Parameter ID. integer
parameterValue# Parameter value. Not needed for MULTIVALUE parameters. String (255)
parameterOptions# For MULTIVALUE parameters only. This should be a comma-separated list, containing those option ID-s that you want to be enabled. All other options will be disabled. string
parameter#optionID#additionalPrice Decimal
***** Components for assembly or bundle products (type ASSEMBLY or BUNDLE)
componentProductID# Component ID. integer
componentAmount# Amount. Decimal

Response

Field name Type Description
productID integer ID of the newly-created item