List of API requests

This is a list of all API functions. Click on function name and you'll find all required and optional input parameters and response fields.


addAssortmentProducts

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/assortment/{id}/products/bulk.

Add products into an assortment.

An assortment defines which products a particular store is allowed to sell and/or to purchase.

To retrieve a list of assortments, see getAssortments. To edit an assortment or add a new one, see saveAssortment. To manipulate with the products associated with an assortment, see API calls getAssortmentProducts, editAssortmentProducts and removeAssortmentProducts. To retrieve all products that can be sold in location according to product status in assortment and it's card see getSellableProducts.

This API call is available only if "Assortments" module has been enabled on your account.


addCustomerAccountToBillingStatement

Add a customer account to a billing statement.


addCustomerRewardPoints

Add a new points transaction and increase customer's point balance.

Typically, reward points accumulate automatically from customer's purchases. You can define the "dollar spent / points earned" ratio in Erply backend, SETTINGS → Configuration → Invoices and Sales. This API function is only for adjusting customer's point balance manually, or for building a custom loyalty program.

To subtract points from customer, see subtractCustomerRewardPoints. To get current point balance for a specific customer, see getCustomerRewardPoints. (There is currently no way to retrieve point balances for all customers simultaneously.)

If you are building a custom loyalty program, you may also take a look at getEarnedRewardPointRecords and getUsedRewardPointRecords — to retrieve a detailed list of all transactions where customer has earned or spent points.


addInvoiceAlgorithmChange

Add a new invoice calculation algorithm change.

After provided date alghoritm with provided version will be used for all invoice calculations.

To get all algorithm changes see getInvoiceAlgorithmChanges, to remove existing algorithm change see removeInvoiceAlgorithmChange.


addItemToMatrixDimension

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/matrix/dimension/value.

Add a new value (specific color or size) to a matrix dimension.

A matrix dimension is necessary for setting up matrix products. Typical matrix dimensions are, for example, "Size" (in which the values might be 2, 4, 6, 8 — or S, M, L, XL) and "Color" (which may contain Blue, Red, Black, Green etc).

To create a new dimension, see saveMatrixDimension. To edit an existing value (to change its name or code), see editItemInMatrixDimension. To delete a value, see removeItemsFromMatrixDimension.


addProductToPriceList

Add a new row to a price list.

To create a price list use the savePriceList API call.

If you want to remove any items from the price list, use the deleteProductInPriceList API call.
To edit products in price list use the editProductInPriceList API call.
To get the products from the price list, use the getProductsInPriceList API call.


addProductToSupplierPriceList

Add a new row to a supplier price list.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)

To create a supplier price list use the saveSupplierPriceList API call.

If you want to remove any items from the supplier price list, use the deleteProductsFromSupplierPriceList API call.
To edit products in the supplier price list use the editProductInSupplierPriceList API call.
To get the products from the supplier price list, use the getProductsInSupplierPriceList API call.


addPromotionCountsToInvoice

Store how many times each promotion has applied to a sale.


addStoreRegionPriceList

Associate a price list with a store region.

Store regions can be used for grouping stores (locations, warehouses). The main feature of store regions is that price lists can also be applied to a region, not just individual stores, thereby simplifying price list management. A region can have an unlimited number of price lists, unlike a location, which is limited to 5 price lists.

To retrieve a list of regions (and price lists associated with them), see getStoreRegions. To reorder region price lists, see editStoreRegionPriceList. To remove a price list from a region, see removeStoreRegionPriceList.

The price lists associated with a region will be automatically applied when making a sale from POS or creating a sales document in Erply back office, or when calling API calculateShoppingCart.

It is also possible to make a price list apply only to a specific customer group, in a region. For that, see API calls addStoreRegionCustomerGroupPriceList, editStoreRegionCustomerGroupPriceList and removeStoreRegionCustomerGroupPriceList.

This API call is available only if "Store regions" module has been enabled on your account.


addStoreRegionCustomerGroupPriceList

Associate a price list with a customer group AND store region.

This price list will apply in that region, to customers of that specific customer group only.

To learn more about regions, see the documentation of API call getStoreRegions. With getStoreRegions, you can retrieve lists of each region's price lists and customer group-specific price lists.

To reorder the price lists associated with a region and customer group, see editStoreRegionCustomerGroupPriceList. To remove a customer group-specific price list from a region, see removeStoreRegionCustomerGroupPriceList.

The price lists associated with region and customer group will be automatically applied when making a sale from POS or creating a sales document in Erply back office, or when calling API calculateShoppingCart.

If you want a price list to apply to all customers in a region, regardless of customer group, see addStoreRegionPriceList instead.

If you want a price list to apply to a customer group in all stores, regardless of region, you can associate it with a customer group instead. This needs to be done in Erply back office (there is no API call for that), but API call getCustomerGroups can report which price lists have been applied to a customer group.

A price list can also be associated with a single customer, or a single store.

This API call is available only if "Store regions" module has been enabled on your account.


addTokenToBillingStatement

Add a token to a billing statement.


adjustBinQuantities

This call is deprecated. We recommend to use WMS API instead.

The corresponding new call is: POST /v1/bin-inventory-record.

Make a bin quantity adjustment which is not related to any sales or purchase document (eg. a discrepancy found in recounting). For quantity adjustments that are related to specific sales or purchase documents, you should use saveBinRecords instead.

Internally, this API call will also create transaction records, just like saveBinRecords does. However, in some cases this interface may be more convenient to use.

You can send multiple records with one API call; append numbers 1, 2, 3, ... to the parameter names to identify values for record 1, record 2, etc. Fore example, binID1, productID1, newAmount1 for the first record, binID2, productID2, newAmount2 for the second one and so on.

There is no hard limit to how many records you can send with one call, but it is recommended to keep it below 500. Also, more records take a longer time to process, so make sure you will not hit a timeout while waiting for API's response.


analyzeInventoryRecords

Analyze the inventory records related to a sales document, purchase document, Inventory Registration, Inventory Write-Off or Inventory Transfer, and detect errors (eg. missing records, duplicate or orphaned records).

This API call is intended for technical maintenance and investigation. We do not expect it to be useful for end-user workflows. There are no guarantees that the returned information is useful for making any decisions, and the API fields are not guaranteed to be stable: fields may be removed or renamed.

The API call should only be used for documents that are actually supposed to have inventory records. Sales orders, sales quotes, purchase orders, for example, do not have inventory records; the API call may report misleading information for these.


applyPromotions

An alias for API call calculateShoppingCart.

calculateShoppingCart takes a list of items and quantities as input, and returns up-to-date item prices and the total value of the cart — with price lists, discounts, promotions, coupons, and taxes automatically applied.


calculateShoppingCart

Calculate the value of a shopping cart, and have discounts, promotions and taxes automatically calculated by API. You only need to input item IDs and quantities.

calculateShoppingCart is a very versatile function that:

  • For each item, finds the sales price that should apply in given location, and to the specified customer.
  • Automatically applies price list prices, discounts and promotion rules.
  • Automatically applies correct tax rate to each item.
  • Calculates invoice net total, tax/VAT and total, using the same algorithm as Erply backend.
You need to input product IDs and quantities, and you may also specify location ID and customer ID.

calculateShoppingCart can be used in web shops, or to easily implement a custom Point of Sale application on top of Erply API. This API call is used by Erply's own Touch POS, so the most up-to-date implementation is guaranteed.

Price list and promotion rules are very complicated and implementing them locally would also mean you need to download huge amounts of data. That is why we recommend to call calculateShoppingCart instead.


cancelInventoryRecords

Cancel specified inventory records.

This API call is for technical maintenance and for resolving issues. It is meant only for internal use by Erply SREs and administrators. We do not make any guarantees that this API call is fit for fixing any particular issue, and we cannot help if usage of the call causes further problems or discrepancies.


changePassword

This call is deprecated. We recommend to use Authentication API instead.

The corresponding new call is: PUT /v1/user/change-password.

changePassword allows you to change user's password. When called, it provides you a "session key" that you can use in subsequent API calls as a token of authentication. When the password is successfully changed, all other session keys for this user that are still valid will be deleted.

This API call may return:

  • Error 1010 if field "oldPassword" or "newPassword" is unset;
  • Error 1016 (errorField="newPassword") if new password does not conform to password requirements, eg. is too short. Currently we require passwords to be at least 8 characters;
  • Error 1012 if new password is equal to old password;
  • Error 1016 (errorField="oldPassword") if old password is incorrect.


The output of this API call is similar to verifyUser and switchUser.


clockIn

Clock in an employee.

Timeclock records are used for Time and Attendance Report. (If you have the module enabled on your Erply account, see Reports » Commission, timeclock » Time and Attendance Report.)

To clock out an employee, use clockOut. To retrieve all timeclock records, use getClockIns.


clockOut

Clock out an employee.

Timeclock records are used for Time and Attendance Report. (If you have the module enabled on your Erply account, see Reports » Commission, timeclock » Time and Attendance Report.)

To clock in an employee, use clockIn. To retrieve all timeclock records, use getClockIns.


setPasswordAsExpired

For use when password rotation settings are used. Sets the input users passwords as expired. When the affected users next time use verifyUser the isPasswordExpired flag will be set to true. verifyUser.


convertAPILanguageIdentifierForPOS

Convert a language identifier used in Erply API (eg. "est", "lit") into a language identifier used by Berlin POS (eg. "en", "ee", "fr" or "cn").

API checks what languages are actually installed on your account. When requesting a non-installed language, API returns error code 1016. If POS does not support the corresponding language, an appropriate fallback value is returned — typically "us" (US English).

This call is specific to Berlin POS. For a more useful alternative, see getActiveLanguages.


convertPOSLanguageIdentifier

Convert a language identifier used in Berlin POS (eg. "en", "ee", "fr" or "cn") into a language identifier used by Erply API.

Many API calls take an input parameter "lang". With this API call you can check what value to use to retrieve product names, product group names, payment methods etc. in a specific language: French, Turkish or any other.

This API call implements two important checks/features:

  • For some languages, an existing language identifier has been overridden (reused); eg. in Erply, on Canadian accounts, French uses the language identifier "lat" (!)
  • It checks what languages are actually installed on your account. If you request Turkish, but this language has not been installed on your account, the API call will point you to a most appropriate fallback, typically English ("eng").

This call is specific to Berlin POS. For a more useful alternative, see getActiveLanguages.


copyMasterListProductsToErply

Copy items from the Master List to Erply's active product catalog.

If the item with same ID does not exist in Erply products, API call adds it (with same ID). Otherwise overwrites product fields with the values from Master List.

For other Master List-related API calls, see findMasterListProducts and saveMasterListProducts.


decrementAttributeValue

Decrement attribute value.

This API call is for editing custom objects. Erply has an object storage where you can store custom data for plug-ins, integrations etc.

For other object storage functions, see getObjects, saveObject, deleteObject (which allow to manipulate whole objects), and incrementAttributeValue, decrementAttributeValue — which provide a way to atomically increment or decrement one numeric field of a specific object (eg. to implement a counter).


deleteAddress

This call is deprecated. For managing customer addresses, use CRM API.

The corresponding new call is: DELETE /v1/addresses/{ids}.

Delete a supplier / customer / company address.

If the deleted address belongs to a customer (to a natural person) and your account country is subject to the General Data Protection Regulation (GDPR), Erply logs the deletion in the customer information processing log.


deleteAppliance

Delete an appliance.

This API call returns error 1006 if assignment module is not enabled on this account.


deleteAssignment

Delete an assignment.

This API call returns error 1006 if assignment module is not enabled on this account.


deleteAssignmentGroup

Delete an assignment group.

This API call returns error 1006 if assignment module is not enabled on this account.


deleteAssortment

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/assortment/{id}.

Delete an assortment.

An assortment defines which products a particular store is allowed to sell and/or to purchase.

To retrieve a list of assortments, see getAssortments. To edit an assortment or add a new one, see saveAssortment. To manipulate with the products associated with an assortment, see API calls getAssortmentProducts, addAssortmentProducts, editAssortmentProducts and removeAssortmentProducts. To retrieve all products that can be sold in location according to product status in assortment and it's card see getSellableProducts.

This API call is available only if "Assortments" module has been enabled on your account.


deleteBillingStatement

Delete a billing statement.


deleteBillingStatementReading

Delete a reading of billing statement.


deleteBinRecords

This call is deprecated. We recommend to use WMS API instead.

The corresponding new call is: DELETE /v1/bin-inventory-record/{id}.

Delete a previously created record (or records). After a record is deleted, API will also update the cumulative quantity of that product in that bin.


deleteCampaign

Delete a sales promotion.


deleteCoupon

Delete a coupon rule.


deleteCustomer

Delete a customer.

If the deleted customer is a natural person and your account country is subject to the General Data Protection Regulation (GDPR), Erply logs the deletion in the customer information processing log.


deleteCustomerAccountFromBillingStatement

Delete billing statement accounts.


deleteCustomerAssociation

Delete a customer's "association".

"Associations" are a specific one-to-many, one-way relationship between customers. A customer can have zero or more "associations", each one of which is a customer in itself, and one of which can be the "default association".

To see a list of a customer's "associations", see getCustomers and pass the flag getAssociationsAndProfessionals = 1. API will also return the IDs of these links.

With deleteCustomerAssociation, you can delete the link between two customers, so that one ceases to be an "association" for the other one.

To create a new link between two customers, see API call saveCustomerAssociation.

An identical feature is "customer's professionals". See saveCustomerProfessional and deleteCustomerProfessional.


deleteCustomerGroup

This call is deprecated. For managing customer groups, use CRM API.

The corresponding new call is: DELETE /v1/customers/groups/{ids}.

Delete a customer group.


deleteCustomerProfessional

Delete a customer's "professional".

"Professionals" are a specific one-to-many, one-way relationship between customers. A customer can have zero or more "professionals", each one of which is a customer in itself, and one of which can be the "default professional".

To see a list of a customer's "professionals", see getCustomers and pass the flag getAssociationsAndProfessionals = 1. API will also return the IDs of these links.

With deleteCustomerProfessional, you can delete the link between two customers, so that one ceases to be a "professional" for the other one.

To create a new link between two customers, see API call saveCustomerProfessional.

An identical feature is "customer's associations". See saveCustomerAssociation and deleteCustomerAssociation.


deleteDeliveryType

Delete a delivery type.


deleteEmployee

This call is deprecated. We recommend to use Account Administration API instead.

The corresponding new call is: DELETE /v1/employee/{employeeId}.

Delete an employee.


deleteEvent

Delete an event.


deleteInventoryRegistration

Delete an Inventory Registration.


deleteInventoryTransfer

Delete an Inventory Transfer.


deleteInventoryWriteOff

Delete an Inventory Write-Off.


deleteLocationInWarehouse

Delete a location in warehouse.

"Location in warehouse" is a product classifier. A product can have one "location in warehouse".

See also getLocationsInWarehouse and saveLocationInWarehouse.


deleteMatrixDimension

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/matrix/dimension/{id}.

Delete a matrix dimension.


deleteObject

Delete an object.

Erply has an object storage where you can store custom data for plug-ins, integrations etc.

For other object storage functions, see getObjects, saveObject, deleteObject (which allow to manipulate whole objects), and incrementAttributeValue, decrementAttributeValue — which provide a way to atomically increment or decrement one numeric field of a specific object (eg. to implement a counter).


deletePayment

Delete a payment.


deletePriceList

Delete a price list.


deleteSalesDocument

Delete a sales document (Invoice, Quote, Sales Order, etc).


deleteStocktaking

Delete a physical stocktaking act.

For related API calls, see getStocktakings, saveStocktaking, getStocktakingReadings, saveStocktakingReadings and incrementStocktakingReading.


deleteSubsidyType

Delete a subsidy type.

API user must have the rights to manage Subsidy types.

This API call returns error 1006 if "Price list row subsidy and other fields module" is not enabled on this account.

To save a new subsidy type or update an existing one, use the saveSubsidyType API call.
To find subsidy types use the getSubsidyTypes API call.


deleteSupplier

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/supplier/{ids}.

Delete a supplier.


deleteSupplierGroup

Delete a supplier group.


deleteTokenFromBillingStatement

Delete billing statement tokens.


deleteProduct

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/product/{ids}.

Delete a product. Products that have any number of transactions associated with them (sales, purchases or inventory) cannot be deleted; API returns error 1063. Instead, we always recommend to archive the product — setting its status to "ARCHIVED".

In Erply backend, deleting products is no longer possible; clicking the "X" button always archives a product.


deleteProductFile

Delete a product file.


deleteProductGroup

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/product/group/{ids}.

Delete a product group. Note that products belonging to this group, as well as subgroups, will NOT be deleted or recategorized.


deleteProductInPriceList

Delete products from the price list.

To add products to price list, use the addProductToPriceList API call.
To edit a product in the price list, use the editProductInPriceList API call.
To retrieve the products that are on the price list, use the getProductsInPriceList API call.


deleteProductPackage

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/product/package/{ids}.

Remove a package option (eg. "a box of 12", or "a pallet of 2500") from a product.

In back office, packages are listed in the subsection Packages on product card.

To get a list of packages for a product (and their IDs, to be able to delete them), call API getProducts and specify flag getPackageInfo = 1.

To add or edit a package, see saveProductPackage.


deleteProductPicture

Delete a product picture.


deleteProductsFromSupplierPriceList

Delete products from the supplier price list.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)

To add products to the supplier price list, use the addProductToSupplierPriceList API call.
To edit a product in the supplier price list, use the editProductInSupplierPriceList API call.
To retrieve the products that are on the supplier price list, use the getProductsInSupplierPriceList API call.br>
This call requires you to know the IDs of the price list items. If you prefer to delete by product ID instead, see removeItemsFromSupplierPriceList.


deleteProject

Delete a project.


deletePurchaseDocument

Delete a purchase document (invoice, order, return).


deleteStoreRegion

Delete a store region.

Store regions can be used for grouping stores (locations, warehouses). The main feature of store regions is that price lists can also be applied to a region, not just individual stores, thereby simplifying price list management. A region can also have an unlimited number of price lists, unlike a location, which is limited to 5 price lists.

To retrieve a list of store regions, see getStoreRegions. To edit a store region or add a new one, see saveStoreRegion. To manipulate with the price lists associated with a region, see API calls addStoreRegionPriceList, editStoreRegionPriceList and removeStoreRegionPriceList.

This API call is available only if "Store regions" module has been enabled on your account.


deleteVatRateComponent

Delete a component of VAT rate (or sales tax / GST / etc. rate, depending on what taxation is used in the particular country).

To create or edit tax component, see saveVatRateComponent.

The following call can be used only if the "City, county and state tax rates" module has been enabled on your account.


deleteCompanyType

Delete a company type. Company types are used to specify business entity type of company client.

To retrieve a list of company types, see getCompanyTypes. To edit a company type or add a new one, see saveCompanyType.


deletePersonTitle

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: DELETE /v1/customers/individuals/titles/{ids}.

Delete a person title. Person titles are used as a prefix for polite client naming.

To retrieve a list of person titles, see getPersonTitles. To edit a person title or add a new one, see savePersonTitle.


deleteJobTitle

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: DELETE /v1/customers/individuals/job-titles/{ids}.

Delete a job title. Job titles are used to specify employee's job area.

To retrieve a list of job titles, see getJobTitles. To edit a job title or add a new one, see saveJobTitle.


deleteBusinessArea

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: DELETE /v1/business/areas/{ids}.

Delete a business area. Business areas are used to specify area of company client.

To retrieve a list of business areas, see getBusinessAreas. To edit a business area or add a new one, see saveBusinessArea.


deletePosGlobalQuickButton

Delete a quick product button from a global list. Quick buttons are displayed in POS for fast access.

To change button position, see API call switchPosGlobalQuickButton.

Insert new button into the list, see API call insertPosGlobalQuickButton.

To retrieve list of buttons, see API call getPosGlobalQuickButtons.


deletePosStoreQuickButton

Delete a quick product button from a store-specific list. Quick buttons are displayed in POS for fast access.

To change button position, see API call switchPosStoreQuickButton.

Insert new button into the list, see API call insertPosStoreQuickButton.

To retrieve list of buttons, see API call getPosStoreQuickButtons.


editAssortmentProducts

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: PATCH /v1/assortment/products/{id}.

Change the status of products in an assortment.

An assortment defines which products a particular store is allowed to sell and/or to purchase.

To retrieve a list of assortments, see getAssortments. To edit an assortment or add a new one, see saveAssortment. To manipulate with the products associated with an assortment, see API calls getAssortmentProducts, addAssortmentProducts and removeAssortmentProducts. To retrieve all products that can be sold in location according to product status in assortment and it's card see getSellableProducts.

This API call is available only if "Assortments" module has been enabled on your account.


editCompanyInfo

Edit information of your own company.

This data set can be queried with API call getCompanyInfo.


editEarnedRewardPointRecord

Edit an existing record in reward point history where a customer has earned reward points.

The history (and transactionIDs) can be retrieved with getEarnedRewardPointRecords.

Under normal circumstances, you should not use this method; this is only for transfering points history from one customer to another, or for correcting errors in points history. To add or remove points, use subtractCustomerRewardPoints and addCustomerRewardPoints instead.

Related API calls for editing reward point usage history are getUsedRewardPointRecords and editUsedRewardPointRecord.


editItemInMatrixDimension

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: PUT /v1/matrix/dimension/value/{id}.

Edit an existing value in a matrix dimension.

A matrix dimension is necessary for setting up matrix products. Typical matrix dimensions are, for example, "Size" (in which the values might be 2, 4, 6, 8 — or S, M, L, XL) and "Color" (which may contain Blue, Red, Black, Green etc).

To create a new dimension, see saveMatrixDimension. To add a new value, see addItemToMatrixDimension. To delete a value, see removeItemsFromMatrixDimension.


editProductInPriceList

Edit an existing record in price list.

API call editProductInPriceList does not allow to change product ID. To switch product, the price list row should be deleted using API call deleteProductInPriceList and a new one should be added using API call addProductToPriceList.
If you need to retrieve the products that are on the price list, use the getProductsInPriceList API call.


editProductInSupplierPriceList

Edit an existing record in supplier price list.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)

API call editProductInSupplierPriceList does not allow to change product ID (nor amount, if Quantity discounts module is enabled). To switch product, the supplier price list row should be deleted using API call deleteProductsFromSupplierPriceList and a new one should be added using API call addProductToSupplierPriceList.
If you need to retrieve the products that are on the supplier price list, use the getProductsInSupplierPriceList API call.


editStoreRegionPriceList

Edit an association between a price list and a store region (change the price list's priority).

Store regions can be used for grouping stores (locations, warehouses). The main feature of store regions is that price lists can also be applied to a region, not just individual stores, thereby simplifying price list management. A region can also have an unlimited number of price lists, unlike a location, which is limited to 5 price lists.

To retrieve a list of regions (and price lists associated with them), see getStoreRegions. To associate a price list with a region, see addStoreRegionPriceList. To remove a price list from a region, see removeStoreRegionPriceList.

The price lists associated with a region will be automatically applied when making a sale from POS or creating a sales document in Erply back office, or when calling API calculateShoppingCart.

This API call is available only if "Store regions" module has been enabled on your account.


editStoreRegionCustomerGroupPriceList

Edit an association between price list, customer group and a store region (change the price list's priority).

To learn more about regions, see the documentation of API call getStoreRegions. With getStoreRegions, you can retrieve lists of each region's price lists and customer group-specific price lists.

To associate a new price list with a region and customer group, see addStoreRegionCustomerGroupPriceList. To remove a customer group-specific price list from a region, see removeStoreRegionCustomerGroupPriceList.

The price lists associated with region and customer group will be automatically applied when making a sale from POS or creating a sales document in Erply back office, or when calling API calculateShoppingCart.

This API call is available only if "Store regions" module has been enabled on your account.


editUsedRewardPointRecord

Edit an existing record in reward point usage history (where an amount has been subtracted from customer's point balance).

The history (and transactionIDs) can be retrieved with getUsedRewardPointRecords.

Under normal circumstances, you should not use this method; this is only for transfering points history from one customer to another, or for correcting errors in points history. To add or remove points, use subtractCustomerRewardPoints and addCustomerRewardPoints instead.

Related API calls for editing the history of earned reward points are getEarnedRewardPointRecords and editEarnedRewardPointRecord.


findMasterListProducts

Look up a Master List product by code. You can use configuration parameter "master_list_min_search_string_length" to set minimum length for the input value. By default 3. You can also use configuration parameter "master_list_max_search_results" to set number of records returned by the request. By default 100.

For other Master List-related API calls, see saveMasterListProducts and copyMasterListProductsToErply.


findProductForStocktaking

Retrieves product information by code or name and it's data related to stocktaking sheet. Call is used for quick search of all data required for update of quantities on stocktaking act, see saveStocktakingReadings (to make bulk updates) or incrementStocktakingReading (to increment quantities atomically). Call will return products with exact match, or up to 100 products matching with search filters, products are ordered by theirlast modification date - newest first. If no products matching with filters were found call will return empty response without any error codes.


getAccountStatements

Retrieve all customers who have a non-zero balance (who have unpaid invoices, prepayments, store credit etc.). For each customer, API returns a link to PDF payment reminder document, and also links to all unpaid invoices in PDF format.

NB! The links are valid for one-time use ONLY. You should download the PDF's and e-mail or display them as needed, but the link should not be shown or forwarded to customer.


getAddresses

This call is deprecated. For managing customer addresses, use CRM API.

The corresponding new call is: GET /v1/addresses.

Retrieve customer, supplier, or company addresses.

Important: if you operate in the European Union, the General Data Protection Regulation (GDPR) requires all processing done with customers' personal information to be logged. If you retrieve customer addresses, you are responsible for logging everything you do with the data. If it is not possible to keep the logs in the system that processes the data, you may consider writing the log entries into Erply, with the logProcessingOfCustomerData call.


getAddressTypes

This call is deprecated. For managing customer addresses, use CRM API.

The corresponding new call is: GET /v1/addresses/types.

Retrieve address types.


getActiveLanguages

Get the list of languages currently activated on this Erply account.

For a list of all supported languages, see getAllLanguages; getActiveLanguages returns a subset of those. For the default language, see getDefaultLanguage.

These two API calls are useful if you are building a frontend application and need to read or write multilingual data (product names, product group names). Using the list of languages, the application can figure out which field name to use for retrieving or updating a product's name in French, for example.

For more information about languages in Erply, see this article.


getAllLanguages

Get the list of all languages that Erply supports.

For a list of languages that are currently activated on the given account, see getActiveLanguages. For the default language, see getDefaultLanguage.

These two API calls are useful if you are building a frontend application and need to read or write multilingual data (product names, product group names). Using the list of languages, the application can figure out which field name to use for retrieving or updating a product's name in French, for example.

The languages listed here cannot be all simultaneously activated; some of these are available in certain countries only, and there is a limit of maximum 10 languages.

For more information about languages in Erply, see this article.


getAllowedWarehouses

This call is deprecated. Use Account Administration API instead.

The corresponding new call is: GET /v1/user/warehouse.

Retrieve warehouses that the specified user has access to. API call getWarehouses, on the other hand, returns all warehouses.


getAmountsOnOrder

Get product quantities on Purchase Orders that have not been fulfilled yet.


getAppliances

Retrieve appliances or vehicles.

This API call is related to the Assignments module. Depending on configuration, your Assignments module may be set up either for appliance repair (in which case it returns the list of appliances), or vehicle/car repair (it returns the list of vehicles). Vehicles have a few extra fields, compared to appliances.

This API call returns error 1006 if assignment module is not enabled on your account.

Important: if you operate in the European Union, the General Data Protection Regulation (GDPR) requires all processing done with customers' personal information to be logged. If the retrieved dataset contains any information that could be considered personally identifiable data of natural persons (vehicle registration numbers and VINs, for example), you are responsible for logging everything you do with the data. If it is not possible to keep the logs in the system that processes the data, you may consider writing the log entries into Erply, with the logProcessingOfCustomerData call.


getAppliedPromotionRecords

Retrieve a list of occurrences where a promotion discount, price list discount or a manual discount has been applied to a retail sale.

This information can be used to build a "discount report", outlining how many times a promotion / price list has been invoked, what items have been purchased with it and what is the total discount that customers have received through each type of discount, each price list and each promotion.

A built-in report providing that information can be found in Erply back office, Reports → Sales Promotions.

To start accumulating the data, get access to that back office report, and to be able to use this API call, please contact customer support and ask them to enable "Promotion Report" extra module on your account.

Likewise, to accumulate inforation about price lists and manual discounts as well, not only promotions, please contact customer support and ask them to additionally enable the following modules on your account:

  • "Applied Price Lists" module;
  • "Applied Manual Discount" module.
However, you also need to use Classic back office (not Berlin), and version 4.5.0 or greater.

Promotions, unlike price lists, are only applied to sales made from Berlin POS, Touch POS and Windows POS. Promotions are NOT applied to sales made from back office.

If you want to build a third-party sales integration that also uses promotions / price lists and generates this data, see calculateShoppingCart and saveSalesDocument. The flow is as follows: you need to pass shopping cart contents into API calculateShoppingCart. API will return prices, discounts and tax rates, and will also inform which promotions and/or price lists it applied to each cart item. When the sale gets confirmed, this data should be passed along to API saveSalesDocument.

Discount records are returned in the order in which they applied. Generally, the order is as follows:
  1. Price list discounts\:
  2. Manual discount\:
  3. Promotion discounts.


There is one exception, however\: if promotion "Get these items for a fixed total $x" applies, manual discount gets overwritten by the fixed price, and is re-applied after the promotion. Therefore, manual discount may occur twice on one invoice line — to one part of the line quantity, the manual discount is applied before all promotions, and to another part of the line quantity it is applied after a specific promotion.


getAssignmentGroups

Retrieve assignment groups.

This API call returns error 1006 if assignment module is not enabled on this account.


getAssignments

Retrieve assignments.

Assignments module is an Erply feature for repair workshops. There are two different configurations: appliance repair and vehicle repair. API call getAppliances lists your appliance/vehicle database.

This API call returns error 1006 if assignment module is not enabled on this account.


getAssortments

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/assortment.

Get a list of assortments.

An assortment defines which products a particular store is allowed to sell and/or to purchase.

To edit an assortment or add a new one, see saveAssortment. To delete an assortment, see deleteAssortment. To manipulate with the products associated with an assortment, see API calls getAssortmentProducts, addAssortmentProducts, editAssortmentProducts and removeAssortmentProducts. To retrieve all products that can be sold in location according to product status in assortment and it's card see getSellableProducts.

This API call is available only if "Assortments" module has been enabled on your account.


getAssortmentProducts

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/assortment/{id}/products.

Get a list of products contained in an assortment.

An assortment defines which products a particular store is allowed to sell and/or to purchase.

To retrieve a list of assortments, see getAssortments. To edit an assortment or add a new one, see saveAssortment. To delete an assortment, see deleteAssortment. To manipulate with the products associated with an assortment, see API calls addAssortmentProducts, editAssortmentProducts and removeAssortmentProducts. To retrieve all products that can be sold in location according to product status in assortment and it's card see getSellableProducts.

This API call is available only if "Assortments" module has been enabled on your account.


getBilledUntilDate

Retrieve "billed until" dates for recurring billings.

This API call calculates the end date of the last billed period for each specified billing. Check these dates against the parameters of respective billings to find out which customers are already due for their next invoice. Detailed information about each billing can be retrieved with API call getBillingStatements.

Most importantly, you need to know:

  • What is the period (cycle) of the recurring billing (field billingStatementPeriod);
  • Whether the customer is billed at the beginning of the billing period, at the end of the period, or is billing based on the readings of a meter (field billingStatementTime);
  • When recurring billing is supposed to begin and/or end (fields startDate and endDate).


For billings that are based on meter readings, a "billing period" is the time span from one reading to the next one; and the "billed until" date is the date of the last invoiced reading.

API returns "0000-00-00" for a particular billing if:
  • The billing has been set up, but no invoices have been issued yet. (In that case, refer to the billing's "start date" instead.);
  • If the billing is currently suspended (deactivated);
  • If no readings have been entered yet, or only the initial reading of the meter has been entered.


Generally, recurring billing works best if invoices are issued in order. If there are any gaps in billing, back office and API at the moment treat fixed-fee billings and metered billings differently. For a fixed-fee billing, API returns the date of the most recent billed period; while for metered billings, API identifies the earliest "gap" in invoices (earliest reading that has not been invoiced yet) and returns the date of the reading before that.


getBillingStatementCustomerAccounts

Retrieve billing statement accounts.


getBillingStatements

Retrieve all recurring billings that have been set up in Erply.

A recurring billing indicates that customer should get a monthly (yearly) invoice for the indicated services, at the indicated price.

After the billing has been set up, recurring invoices need to be manually created and sent from back office Sales → Recurring billing, at the beginning or at the end of a month, as appropriate.

Alternatively, invoices can also be created over API with the saveSalesDocument call, and associated with the billing via the "billingStatementID" field.

To get the "billed until" date for each recurring billing, see API call getBilledUntilDate.


getBillingStatementReadings

Retrieve billing statement readings.


getBillingStatementTokens

Retrieve billing statement tokens.


getBinQuantities

Retrieve the cumulative quantities in bins.


getBinRecords

Retrieve the list of bin records.


getBins

This call is deprecated. We recommend to use WMS API instead.

The corresponding new call is: GET /v1/bin.

Retrieve the list of bins (for one warehouse, or all warehouses, or specific bins by ID).


getBrandDiscountsFromPriceLists

Retrieve brand discounts.


getBrands

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/brand.

Retrieve product brands.

Brands are a way of categorizing your product database, and several API calls support filtering by brand.

Products can additionally be organized into groups (getProductGroups, hierarchical), categories (getProductCategories, hierarchical), and priority groups (getProductPriorityGroups, a flat list).


getBusinessAreas

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: GET /v1/business/areas.

Get a list of business areas. Business areas are used to specify area of company client.

To edit a business area or add a new one, see saveBusinessArea. To delete a business area, see deleteBusinessArea.


getCampaigns

Retrieve sales promotions.

This API call will return descriptions of promotion rules, which are generally structured as follows: "Customer must do/buy X and will get Y" (a discount, special price etc.)

For an API call that automatically implements all promotion rules and price lists automatically for you, see calculateShoppingCart.

To create a promotion rule, see saveCampaign.

In order to manage the new multi warehouse links, see getCampaignWarehouses.


getCampaignWarehouses

Get the list of warehouses the promotion applies for. In order to add more warehouses use saveCampaignWarehouse and in order to remove existing links use removeCampaignWarehouse.


saveCampaignWarehouse

Add a new warehouse link to a promotion. In order to get existing warehouse links use getCampaignWarehouses and in order to remove existing ones use removeCampaignWarehouse.


removeCampaignWarehouse

Remove a warehouse link from a promotion. In order to get existing warehouse links use getCampaignWarehouses and in order to add new links use saveCampaignWarehouse.


getCashIns

This call is deprecated. We recommend to use Point of Sale API instead.

The corresponding new call is: GET /v1/cash/list.

Retrieve POS cash drops and cash payouts.

A cash drop can be recorded with API call POSCashIN and a payout with POSCashOUT. These operations are printed on the register's day-end Z Report.

By convention, a cash drop with an amount of 0 is an indicator of "No Sale", ie. just opening the drawer.


getChangedDataSince

Get information about what items have been created, updated or deleted in the server since the given timestamp.

Function output lists the various modules (data tables) in the system, whether there have been additions/updates, and whether there have been deletions in the particular module.


getClockedInEmployees

Retrieve currently clocked-in employees.

An employee can be clocked in with API call clockIn and clocked out with clockOut.

Timeclock records can be retrieved with API call getClockIns.


getClockIns

Retrieve timeclock records.

An employee can be clocked in with API call clockIn and clocked out with clockOut.

Timeclock records are used for Time and Attendance Report. (If you have the module enabled on your Erply account, see Reports » Commission, timeclock » Time and Attendance Report.)


getConfParameters

Get account configuration — all the settings from the module Settings > Configuration and also a number of hidden settings that can be enabled by Erply technical support.

This API call returns exactly one result record. This record contains a variable number of attributes and it is not guaranteed that any one of these attributes will be present. The contents of this record should be saved into a dictionary or an associative array, and a default value (0, unless specified otherwise) assumed for all missing ones.

Some of the parameters are supposed to have a decimal/integer value, or a value of 1 or 0 (true/false, enabled/disabled). However API returns almost all fields as strings. If your programming environment requires that, please cast the parameters to the correct type. In the table below, the types are marked with an asterisk.

Most — but not all! — settings can be edited using saveConfParameter. Do NOT edit any undocumented settings or those marked as "Not Editable".


getCostOfGoodsSold

This call is deprecated. We recommend to use the Reports API instead.

The corresponding new call is: GET /v1/generated-reports/cogs-invoice-rows.

Get the cost of goods sold for a given period. API returns an array of all sales document rows in the selected period, and the cost for each row.

Erply calculates cost according to FIFO principle.

Usage guidelines: Note that the COGS of any sale may change at any time — Erply does not freeze cost at the moment when sale takes place. Many kinds of operations may adjust it, eg. entering or correcting a purchase invoice at a later date, adding freight costs, deleting other documents etc. Find out what are the accounting principles in your company and pull COGS only when all adjustments for the given period are done — eg. at the end of month.


getCountries

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/product/country.

Get the list of countries. Countries are a way of categorizing your customer and supplier databases.


getCoupons

Get coupon rules.

Coupon rule is like the "blueprint" or "type" of a printed coupon (that is issued from POS and handed to a customer). The "blueprint" specifies in what circumstances the coupons will be printed from POS, and what promotion will apply when customer returns with the coupon — ie., what discount or extra value it effectively carries.

A coupon rule should be associated with a sales promotion (see getCampaigns).

In order for the customer to use those discounts, you need to issue the customer a coupon with an unique serial number (see getIssuedCoupons, saveIssuedCoupon). When customer returns with the coupon code, it has to be scanned at the POS. Scanning redeems the coupon, invokes the promotion associated with it, and gives customer a discount.

To create a coupon rule, see saveCoupon.


getCustomerGroups

Get customer groups. In Erply, customer groups are hierarchical; a group can contain sub-groups.


getCustomers

Retrieve your customer database.

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

  • customer addresses (set getAddresses = 1);
  • customer contact persons (set getContactPersons = 1);
  • customer balance (set getBalanceInfo = 1)
To add or edit a customer record, use saveCustomer.

Each customer belongs to a customer group (see getCustomerGroups).

To retrieve current reward points balance for a particular customer, see getCustomerRewardPoints.

Important: if you operate in the European Union, the General Data Protection Regulation (GDPR) requires all processing done with customers' personal information to be logged. Every time you retrieve customer information with the getCustomers call, you are responsible for logging everything you do with the data. If it is not possible to keep the logs in the system that processes the data, you may consider writing the log entries into Erply, with the logProcessingOfCustomerData call.


getCompanyInfo

Get information about the company running the account.

Note that Erply allows to set different contact information for each store (location, warehouse). Each store may have a different phone number, e-mail address, postal address. In Erply back office, you can set that on location card.

Even company name, registry number and VAT number can be customized per-location — although you will probably need that only if your company is a franchise chain consisting of different corporate entities; and you are using a single Erply account, instead of a separate account for each entity.

To retrieve per-location information, see API getWarehouses. Only if a location does not have eg. a phone number, you can fall back to the corporate phone number.

This data set can be edited with API call editCompanyInfo.


getCurrencies

Get currencies (that have been defined on your Erply account).


getCustomerBalance

Retrieve current balance (store credit) for requested customers.


getCustomerBalances

Retrieve current balance (store credit) of all customers.

NB! This API call is essentially a report and can take a long time to run. Avoid calling it too frequently. API processes getCustomerBalances calls one at a time; if you issue another call while previous one is running, API returns error 1021.

Balance is essentially the difference between customer's total invoices and total payments. As such, balance cannot be adjusted directly. To change customer's balance (or to import initial balances), either create a payment (savePayment) or an unpaid invoice (saveSalesDocument).

When you create an invoice and want it to be paid off of customer's store credit (prepaid balance), set input parameter amountPaidWithStoreCredit.

If this call returns error 1006, please contact Erply helpdesk to update your account.


getCustomerRewardPoints

Get customer's current number of reward points.

Reward points accumulate automatically from customer's purchases. In Erply backend, you can set up how many reward points a customer earns for each $1 spent, and the reward points will accrue automatically from that point on.

To subtract the points ("redeem" or "use" them), use subtractCustomerRewardPoints.

Unfortunately, there no way yet to retrieve point balances for all customers simultaneously.

To add points manually (although you typically do not need to do that), see addCustomerRewardPoints. If you are building a custom loyalty program, you may also take a look at getEarnedRewardPointRecords and getUsedRewardPointRecords — to retrieve a detailed list of all transactions where customer has earned or spent points.


getDayClosings

This call is deprecated. We recommend to use Point of Sale API instead.

The corresponding new call is: GET /v1/shift/.

Retrieve a log of POS day openings and closings.

POS can be opened with POSOpenDay and closed with POSCloseDay.

Each returned record corresponds to one day (or one cashier's shift) in one specific register.

If POS has been configured to accept and count multiple currencies, then for each day there will be a separate record for each currency.


getDayOpenings

An alias for getDayClosings.


getDefaultCustomer

Get the ID of default customer used for POS transactions (typically, "POS Customer", "Walk-in" or similar).

If such a customer is not defined, API returns no records.


getDefaultLanguage

Get the default language for this Erply account.

For a list of all supported languages, see getAllLanguages; for a list of currently activated languages, see getActiveLanguages.

For more information about languages in Erply, see this article.


getDeliveryTypes

Get delivery types.

"Delivery type" is a classifier for categorizing sales orders. To assign delivery type to a sales order, pass the deliveryTypeID input parameter to saveSalesDocument.

See also saveDeliveryType, deleteDeliveryType.


getDeliveryTerms

Get delivery terms.

To assign delivery term to a supplier, pass the deliveryTermsID input to saveSupplier.


getDocumentStatuses

Retrieve document statuses.
Note: Documents module in Erply is being phased out and is no longer developed.


getDocumentTypes

Retrieve document types.
Note: Documents module in Erply is being phased out and is no longer developed.


getDocumentSeries

Retrieve document series.
Note: Documents module in Erply is being phased out and is no longer developed.


getEarnedRewardPointRecords

Retrieve all transactions where customers have earned reward points.

This API call is for building custom loyalty programs. For other related calls, see addCustomerRewardPoints (to add points to a customer manually) and getUsedRewardPointRecords (to retrieve transactions where customers have spent reward points}.

For simpler integrations, you will more likely need getCustomerRewardPoints to retrieve a customer's point balance, and subtractCustomerRewardPoints to subtract points from customer.

To edit one specific record, use editEarnedRewardPointRecord. (Under normal circumstances, you should not use that method; this is only for transfering points history from one customer to another, or for correcting errors in points history. To add or remove points, use subtractCustomerRewardPoints and addCustomerRewardPoints instead.)


getEDocuments

if ID is specified, returns the corresponding EDocument. Otherwise returns a list of EDocuments, according to the supplied filtering parameters.


getEmailAccounts

This call is deprecated. Using Erply as an email client is no longer supported.

Returns the list of configured email accounts and the access credentials for each account.


getEmployees

This call is deprecated. We recommend to use Account Administration API instead.

The corresponding new call is: GET /v1/employee.

Retrieve list of employees.

To create an employee, or update employee information, see API call saveEmployee.

For other employee-related API calls, see:

  • recordGDPRConfirmation - to record that the employee agrees to follow the data protection requirements of General Data Protection Regulation;
  • getSchedule - to retrieve employees' work schedules. (This is a salon-specific feature, and not actively in use any more.)
  • getTimeSlots - to retrieve available time slots in employee's schedule. (This is a salon-specific feature, and not actively in use any more.)


getEmployeeStats

Retrieve some total figures about employee sales performance. Currently this method only returns information about the currently authenticated user. Calling this method does not require any user rights.

This method returns only one record, with the fields described below.

These figures may be approximate, Erply may use optimizations to return these figures quickly (eg. to cache the calculated values). For authoritative sales data, see API call getSalesReport.

Unfortunately, timeclock records are not available over the API yet.

This call has been built for Berlin POS, and might not be useful for other use cases.


getEvents

Retrieve events or appointments.

In Erply backend, events (appointments) are listed in the Calendar » Tasks module.

To edit or add an event, use saveEvent.


getEventStatuses

Retrieve event statuses.

Statuses can be added or edited with saveEventStatus.


getEventTypes

Retrieve event types.

Types can be added or edited with saveEventType.


getFranchiseSalesDocuments

Retrieve confirmed sales documents from the reporting account which have the specified type and invoice number. If this account does not belong to a franchise, API returns error 1067.


getFulfillableOrders

This call is deprecated. We recommend to use the Reports API instead.

The corresponding new call is: GET /v1/orders/fulfillable.

Retrieve sales orders that can be fulfilled.


getGiftCardRedeemings

Return an array of gift card redeemings.

This API call returns error 1006 if "Gift card extras" module is not enabled on this account.


getGiftCards

Retrieve gift cards.

To create a new gift card, or update the balance of an existing gift card, use saveGiftCard. To get a log of gift card redeemings, see getGiftCardRedeemings.

In Erply, gift cards have a "balance". A gift card can be used multiple times, until all the balance has been spent. A customer can use any gift card that has not expired and has a non-zero balance.

See getGiftCardTypes to get the the possible types.


getGiftCardTypes

Retrieve gift card types. See getGiftCards for gift cards.


getHomeStores

Get a list of Home Stores (Sign-up Stores).

Customers have two properties, "Home Store" (the one they visit most often) and "Sign-up Store" (where they were first registered as a loyal customer). In franchise accounts, the list of Home Stores / Sign-up Stores can be larger than just the list of account's own stores (locations). Therefore, to populate the respective drop-downs on customer form, use this API call instead of getWarehouses.

Additionally, getHomeStores will not return those locations that have been designated as the "offline warehouses" for returned items.


getInventoryRegistrations

Retrieve Inventory Registrations.

Inventory Registration is a document that takes products into inventory; it has a list of items and quantities. It is similar to a Purchase Invoice, but has fewer fields and is best suited for registering your initial stock quantities when you start using Erply — or for making inventory quantity adjustments.

Non-stock products and bundles cannot be on Inventory Registrations (these items do not have inventory).

Products can be removed from stock with Inventory Write-offs (see getInventoryWriteOffs) and moved between locations with Inventory Transfers (see getInventoryTransfers).

To create an Inventory Registration, see saveInventoryRegistration.


getInventoryTransferReport

Get an inventory transfer report.

API returns a link to CSV file that contains the report.

To retrieve the documents (Inventory Transfers) themselves, see getInventoryTransfers.

Sales and purchase data is also available in report format. See getSalesReport and getPurchaseReport.


getInventoryTransfers

Retrieve Inventory Transfers.

In Erply, an Inventory Transfer is a document that moves inventory between locations (stores); subtracts from one location and adds to the other. An Inventory Transfer contains a list of products and quantities.

Non-stock products and bundles cannot be transfered (these items do not have inventory).

To create or update an Inventory Transfer, see saveInventoryTransfer. To delete one, see deleteInventoryTransfer.

To get a CSV report of Inventory Transfers, see getInventoryTransferReport. If you need all Transfers that have taken place in a certain time period, it is more efficient to get the report — you will get all the data with just one query.


getInventoryWriteOffs

Retrieve Inventory Write-Offs.

Inventory Write-Off is a document that removes products from inventory; it contains a list of items and quantities.

Products can be added to stock with Inventory Registrations (see getInventoryRegistrations) and moved between locations with Inventory Transfers (see getInventoryTransfers).

To create an Inventory Write-Off, see saveInventoryWriteOff. To delete one, see deleteInventoryWriteOff.


getInvoicePaymentTypes

Retrieve invoice payment methods.

"Payment type" or expected payment method is an informative field on invoices. It indicates how the invoice will likely be paid by the customer. (However, keep in mind that actual payments on the invoice may be different from expected payment type.)

To add a new type or edit an existing one, see saveInvoicePaymentType.


getInvoiceAlgorithmChanges

Retrieve invoice calculation algorithm changes. Contains dates and algorithm versions applied at that date and after it.

To add a new algorithm change see addInvoiceAlgorithmChange, to remove existing algorithm change see removeInvoiceAlgorithmChange.


getIssuedCoupons

Get the list of coupons that have been printed from POS and issued to customers.

Coupons are used in Erply to give promotional discounts. Coupons can be printed from POS and given to customers. If customer returns to the store, presents the coupon and cashier scans coupon code, a specific promotion will apply to the ongoing sale.

Issued coupons can be registered in Erply with saveIssuedCoupon. If customer returns to the store with a coupon, it can be validated with verifyIssuedCoupon and then redeemed with redeemIssuedCoupon. To apply coupon discount to a sale, pass coupon code to API call calculateShoppingCart. calculateShoppingCart will also notify you whether the coupon was applicable to that particular shopping cart or not.

This API call returns error 1006 if promotions module is not enabled on this account.


getLocationsInWarehouse

Retrieve list of locations in warehouse.

"Location in warehouse" is a product classifier. A product can have one "location in warehouse".

See also saveLocationInWarehouse and deleteLocationInWarehouse.


getMatrixDimensions

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/matrix/dimension.

Returns an array of possible matrix dimensions.


getObjects

Retrieve your custom objects.

Erply has an object storage where you can store custom data for plug-ins, integrations etc.

For other object storage functions, see getObjects, saveObject, deleteObject (which allow to manipulate whole objects), and incrementAttributeValue, decrementAttributeValue — which provide a way to atomically increment or decrement one numeric field of a specific object (eg. to implement a counter).


getOAuthConfiguration

This API call is used for verifyOAuthToken and createUserFromOAuthToken configuration retrieving. Data can be saved using call getOAuthConfiguration.

Here is the intended use case explained in more detail.


getPayments

Retrieve payments.

In Erply, a payment is associated with a customer (customerID), and optionally an invoice (documentID; or some other sales document, eg. a sales order). One invoice can have many payments. Payment, on the other hand, can only be associated with one invoice at a time. If customer makes an aggregate payment towards several invoices, it needs to be split up into parts.

A payment may not always be associated with a specific invoice (eg. deposits, store credit).

To register a new payment or update an existing one, see savePayment.


getPaymentTypes

Retrieve payment types.

To create a new payment type, see savePaymentType.


getPointOfSaleDayTotals

Returns today's cash, card and other payment type totals for the specified register (point of sale) or for a specific day.

This API call is for implementing a day closing procedure in POS. API provides day totals as recorded by Erply; cashier can then input actual counted amounts and reconcile the differences.

The returned totals include all payments that have taken place since the day was opened at the register. If you provide input parameter "openedUnixTime", API will check if a day was opened at that time; if it does not find that day opening event, an empty response is returned. If the parameter is omitted, API will automatically fetch the latest opening of the register.

This API call can also be called after the day closing procedure, should it be necessary.

If you are looking for X Report / Z Report printouts, see API call getReports.

To open or close the register, see POSOpenDay and POSCloseDay.

In order to use drawer counting feature use POSOpenDayV2 to open the days instead.


getPointOfSaleStatuses

Retrieve statuses ('open' or 'closed') of all registers (points of sale), in all shops and locations.

lastUpdated records will be zero for timestamp and empty for date if this register wasnt open or closed before.


getPointsOfSale

Retrieve all registers (points of sale), in all shops and locations. One shop can have many registers. A register has field "warehouseID" to indicate which store or warehouse it is located in.

To modify, add, or delete registers, please see Account Admin API and the following endpoints:

  • PUT /v1/pointofsale
  • POST /v1/pointofsale
  • DELETE /v1/pointofsale/{pointOfSaleId}

Note: Account Admin API offers a REST interface for retrieving registers — and also lets you create new registers and modify and delete existing ones. (Erply API does not have this functionality.)


getPosGlobalQuickButtons

Retrieve quick product button global list. Quick buttons are displayed in POS for fast access.

To change button position, see API call switchPosGlobalQuickButton.

To delete button from list, see API call deletePosGlobalQuickButton.

Insert new button into the list, see API call insertPosGlobalQuickButton.


getPosStoreQuickButtons

Retrieve quick product button store-specific list. Quick buttons are displayed in POS for fast access.

To change button position, see API call switchPosStoreQuickButton.

To delete button from list, see API call deletePosStoreQuickButton.

Insert new button into the list, see API call insertPosStoreQuickButton.


getPrepaymentPercentages

Retrieve prepayment percentages.

This is a list of predefined options that user can choose from — to set what fraction of the invoice the customer must pay in advance. This list is used:

  • For Laybys in POS;
  • For Prepayment Invoices in Erply back office.


getPriceLists

Returns price lists and the contents of each price list.

Price lists may contain three types of "rules": 1) fixed prices for specified products; 2) fixed prices for specified services; 3) percentage discounts for specified product groups. (A discount applies to all products in this group and its subgroups.)

There can be multiple price lists associated with location, customer, or customer group and the price lists interact with each other and override each other in various ways. To apply all applicable price lists and promotions to a sale, we recommend to use API call calculateShoppingCart. (As input, you need to send all the items on your receipt. API will return the same list, with final prices for each item added.)

Re–implementing all price list rules in your application would be a major undertaking, and we plan to constantly add new promotion features to Erply.

If you need to add products to a price list, then use the addProductToPriceList API call.
To edit products on the price list use the editProductInPriceList API call.
To delete a product from a price list, use the deleteProductInPriceList API call.
To get only the products on the price list, use the getProductsInPriceList API call.


getProductCategories

Retrieve the list of product categories.

Categories are a way of categorizing your product database, and several API calls support filtering by category.

Products can additionally be organized into groups (getProductGroups, hierarchical), brands (getBrands, a flat list) and priority groups (getProductPriorityGroups, a flat list).

Note: PIM API offers a REST interface for retrieving and managing product categories.


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.


getProductsFromSupplierPriceLists

Returns supplier price list products.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)

API user must have the view rights for all supplier price lists.


getProductsInPriceList

Returns products that are on the price list.

API user must have the view rights for all price lists.

To add a new price list, use the savePriceList API call.
If you need to add products to a price list, use the addProductToPriceList API call.
To edit products on the price list, use the editProductInPriceList API call.
To delete products from the price list, use the deleteProductInPriceList API call.


getProductsInSupplierPriceList

Returns products that are on the supplier price list.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)

API user must have the view rights for all supplier price lists.

To add a new supplier price list, use the saveSupplierPriceList API call.
If you need to add products to a supplier price list, use the addProductToSupplierPriceList API call.
To edit products on the supplier price list, use the editProductInSupplierPriceList API call.
To delete products from the supplier price list, use the deleteProductsFromSupplierPriceList API call.


getProductExtraField1Values

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/product/extra/field-1.

Retrieve values for product card extra field 1 (the options in the "Extra field 1" dropdown on product card).

This API call is available only if "Extra product card fields" module is enabled on your account.


getProductExtraField2Values

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/product/extra/field-2.

Retrieve values for product card extra field 2 (the options in the "Extra field 2" dropdown on product card).

This API call is available only if "Extra product card fields" module is enabled on your account.


getProductExtraField3Values

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/product/extra/field-3.

Retrieve values for product card extra field 3 (the options in the "Extra field 3" dropdown on product card).

This API call is available only if "Extra product card fields" module is enabled on your account.


getProductExtraField4Values

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/product/extra/field-4.

Retrieve values for product card extra field 4 (the options in the "Extra field 4" dropdown on product card).

This API call is available only if "Extra product card fields" module is enabled on your account.


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.


getProductsWithChangedPrices

Get list of product IDs whose prices have changed since the specified timestamp. The response does not mean that the prices of all these products have actually changed for any particular store. The price list where the change was made could be inactive, expired, or not associated with any stores at all. Similarly, the response of the API call does not list ALL products whose price might have changed. A product's final store price may also change when:

  • A price list is removed from a store;
  • The order of store price lists is changed;
  • A price list is deleted;
  • A price is deleted from a price list;
  • A product group discount in a price list is added, modified, or removed;
  • Pricing algorithm settings are adjusted.


getProductCostForSpecificAmount

Get FIFO unit cost for a specific amount of specific items you are planning to subtract from inventory.

API inspects all the batches that are currently in stock, calculates (according to FIFO rules) how many items should be discounted from which batch (starting with the oldest ones), and returns the weighted average cost of the resulting lot.

This API call is useful when you plan to make an inventory transaction (eg. a sale, transfer or inventory writeoff), but want to know the exact total cost of the items before actually making the transaction.

You need to specify amount, because each batch may have a different cost. The amount that you require may have to be pulled from one or multiple batches, depending on how many items are left in each batch.

Please contact Erply support if you plan to use this API call. Your account may need updates or customizations to be applied.


getProductFiles

Retrieve 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.

The same information is also available through API call getProducts (field relatedFiles), so if you need to query product information anyway, getProducts API call can also provide you the list of associated files.


getProductFileTypes

Returns an array of product file types.


getProductGroups

Returns a HIERARCHICAL array of product groups.

Groups are a way of categorizing your product database, and several API calls support filtering by group.

Products can additionally be organized into categories (getProductCategories, hierarchical), brands (getBrands, a flat list), and priority groups (getProductPriorityGroups, a flat list)

Note: PIM API offers a better REST interface for retrieving and managing product groups.


getProductLastPurchasePrice

Retrieve the last purchase price of selected products in one specific warehouse.


getProductPackageTypes

Retrieve product package types. Type IDs are needed when saving product packages with API saveProduct.


getProductPictures

Retrieve 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.

The same information is also available through API call getProducts (field images), so if you need to query product information anyway, getProducts can also provide you the list of images for each product.


getProductPrices

Retrieve a product's net sales price in a certain location, or net sales price for a specific customer — according to any price lists that apply.

You can query prices for a single product (by supplying parameter productID) or multiple products at a time (by supplying parameter productIDs).

If you do not want a price for a specific customer or location, but just need to know which price lists contain a specific item, see getProductPricesInPriceLists.


getProductPricesInPriceLists

Retrieve a product's net sales price in price lists.

This API call does not use result paging; all results are returned.

You can query prices for a single product (by supplying parameter productID) or multiple products at a time (by supplying parameter productIDs).

Note that price lists can cumulate or override each other (price lists can apply to locations, as well as customers and customer groups), and price lists can also specify discount percentages for certain product groups. Therefore this API call does not help you to find the current appropriate sales price for an item. For that purpose, use calculateShoppingCart. If you only need to apply price lists, not promotions, you may also use getProductPrices.

API call getProducts can also provide a list price for a specific customer and location, along with other product information.

To retrieve price lists together with all their contents, see getPriceLists.


getProductPriorityGroups

Returns an array of product priority groups.

Priority groups are a way of categorizing your product database, and several API calls support filtering by priority group.

Products can additionally be organized into groups (getProductGroups, hierarchical), categories (getProductCategories, hierarchical), and brands (getBrands, a flat list).


getParameters

Retrieve product parameters.

"Product parameters" is a Erply add-on module, primarily for web shops. (It is not enabled by default. If you are looking for a simple way to attach extra key-value data to products, you may want to consider using attributes instead.)

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

Then, on product card, you can set specific parameter values for each item (eg. Refrigerator XYZ has a volume of 250 L, energy rating "A+" and measures 500 x 650 x 1700 mm).

This API call will return list of parameters and which parameter group they belong to. Unfortunately, API does not have calls for listing all the groups yet, or querying which product groups are associated with which parameter groups.

To get products and their parameter values, use API call getProducts, set getParameters = 1 and see output field "parameters".


getProductUnits

Returns an array of product units.

Note: PIM API offers a REST interface for retrieving and managing product units.


getProjects

Returns an array of projects.


getProjectStatuses

Returns an array of possible project statuses.


getProjectTypes

Returns an array of possible project types.


getPurchaseDocuments

Returns a list of purchase documents (purchase invoices or orders), according to the supplied filtering parameters.

If you have specified document ID or invoice number, or if the search criteria match a single sales document, or if you have set getRowsForAllInvoices = 1, API returns all documents together with their rows. Otherwise only document headers will be returned.

If you are looking for a way to pull all purchase data for external processing, see getPurchaseReport. getPurchaseReport can output either detailed data or aggregate it as needed: it can provide totals by products, by product groups, by dates, by locations, etc.


getPurchaseDocumentStatuses

Returns an array of purchase document possible statuses.


getPurchaseReport

Retrieve a purchase report.

API returns a link to CSV file that contains the report.

Sales and Inventory Transfers are also available in report format. See getSalesReport and getInventoryTransferReport.


getReasonCodes

This call is deprecated. We recommend to use Account Administration API instead.

The corresponding new call is: GET /v1/reason-code.

Get a list of reason codes.


getReceiptPrints

Get a list of receipt printings.

To register that a receipt has been printed, use API call registerReceiptPrint.

The presence of this API call does NOT mean that Erply back office, API and point-of-sale applications actually register all printings of invoices and receipts, and that all this information is already available over API. If you have a particular feature you want to implement, you need to create the full workflow yourself, using this pair of API calls — "registerReceiptPrint" and "getReceiptPrints".

At the moment, only Berlin POS uses the "registerReceiptPrint" call, and only on Swedish accounts — to meet the needs of Swedish Z Reports.

To get the printing log for one specific receipt, see getPrintsForOneReceipt.


getRecentWikiArticles

Get a list of recent wiki articles.


getPrintsForOneReceipt

Retrieve the log: when a particular sales document has been printed.

To register that a receipt has been printed, use API call registerReceiptPrint.

The presence of this API call does NOT mean that Erply back office, API and point-of-sale applications actually register all printings of invoices and receipts, and that all this information is already available over API. If you have a particular feature you want to implement, you need to create the full workflow yourself, using these API calls — registerReceiptPrint, getReceiptPrints and getPrintsForOneReceipt.

At the moment, only Berlin POS uses the "registerReceiptPrint" call, and only on Swedish accounts — to meet the needs of Swedish Z Reports.

To get a list of everything that has been printed in a certain period, see getReceiptPrints.


getRedeemedCoupons

Get a list of coupons that have been redeemed at the register.

For a more generally useful API call, see getIssuedCoupons. getIssuedCoupons lists coupons with ALL statuses — active, expired, redeemed — and you can also use a status filter to retrieve any of the three.


getRegisterTotalSalesOverTime

Get the total value of all transactions made in the specified register over time (all transactions that have accumulated in Erply).

This API call has been implemented to meet a specific requirement for Swedish Z Reports. For more general sales reports, please see getSalesReport.


getReports

Retrieve an "X Report" or "Z Report".

X / Z Report is a report of POS transactions and payments. The output is identical, but an X report is typically printed during the day, and a Z report at the end of the day, after counting the cash drawer.

X / Z Report can be retrieved either as structured data or HTML.

For other reports, see the following API calls:



To get day's payment totals by type (before the cashier starts counting the cash in the drawer), see the API call getPointOfSaleDayTotals.


getReservedStock

Retrieve a list of reserved product quantities (ie. all products that have been reserved with a Sales Order, Prepayment Invoice, or a Sales Quote).

If you subtract the "reserved" quantity from your total inventory, you'll get the "available" quantity — the amount that can be sold while still leaving enough inventory for fulfilling Sales Orders.

API call getProductStock can also list the total inventory, and many other things, besides reserved amounts; getReservedStock is an optimized API call for retrieving just one piece of information.

If you need to get reserved stock across all locations then use API call syncTotalProductStock


getRoundedSales

Retrieve invoices to which rounding was applied.

This API call may be useful for a report which needs to summarize and show amount of applied rounding separately from sales revenue.

Rounding can be configured in back office, Settings → Configuration (all invoice totals to be rounded to the nearest 5 cents, 10 cents or full currency units) or in POS (receipt total to be rounded only if customer pays in cash).

This report only returns confirmed Invoices, Invoice-Waybills, Receipts and Credit Invoices — ie., sales documents that incur sales revenue.

API call getSalesDocuments can be used to retrieve full data about documents.


getSalesDocuments

Retrieve sales documents (invoices, waybills, credit invoices, quotes or orders), according to the supplied filtering parameters.

If you have specified document ID or invoice number, or if the search criteria match a single sales document, or if you have set getRowsForAllInvoices = 1, API returns all documents together with their rows. Otherwise only document headers will be returned.

To create a new sales document (invoice, order or quote), see saveSalesDocument.

If you are looking for a way to pull all sales data for external processing, see getSalesReport. getSalesReport can output either detailed data or aggregate it as needed: it can provide totals by products, by product groups, by dates, by locations, etc.


getSalesDocumentActualReportsHTML

Get an Actual Reports HTML printout for a sales document.

Actual Reports is a visual template designer integrated into Erply. Actual Reports templates can be managed in Erply back office. Erply provides a few basic templates by default, but new ones can be designed as needed. Back office lets you download a custom printout as a PDF document; the same document in HTML format is available with this API call.

The Sales Document API has a call for fetching an Actual Reports printout as PDF, and for sending the PDF by email.


getSalesDocumentActualReportsDataset

Get an Actual Reports dataset for a sales document.

This API call returns basically the same result as back office sends to Actual Reports. The only difference is in VAT components and attributes - spaces in parameter names have been replaced with underscores.

This dataset is intended to be placed into an HTML template; each of these fields is a fragment of HTML and may contain HTML tags.

If you need to use this data in a non-HTML context, you should decode it appropriately:

  1. Replace <br> tags with newlines.
  2. Strip all other HTML tags.
  3. Decode HTML entities.


Most of the date, number and currency fields are referred to as being returned in a "localized format". This means that the values are formatted according to account settings, as defined in back office, in the Settings → Configuration module.


getSalesReport

Get a sales report.

API returns a link to CSV file that contains the report. Field separator in the CSV is region- and configuration-specific — check getConfParameters, field "csv_field_separator".

If you want to display sales totals in graph format, and would like to retrieve a simpler data set, see the following API calls:



Purchases and Inventory Transfers are also available in report format. See getPurchaseReport and getInventoryTransferReport.


getSalesTotalsByEmployeeAndDay

Get recent daily sales totals by employee.

This a concise data set that suits best for displaying a graph. To get a full sales report, see getSalesReport.

See also getSalesTotalsByEmployeeAndMonth, getSalesTotalsByWarehouseAndDay, and getSalesTotalsByWarehouseAndMonth.


getSalesTotalsByEmployeeAndMonth

Get recent monthly sales totals by employee.

This a concise data set that suits best for displaying a graph. To get a full sales report, see getSalesReport.

See also getSalesTotalsByEmployeeAndDay, getSalesTotalsByWarehouseAndDay, and getSalesTotalsByWarehouseAndMonth.


getSalesTotalsByWarehouseAndDay

Get recent daily sales by store (location).

This a concise data set that suits best for displaying a graph. To get a full sales report, see getSalesReport.

See also getSalesTotalsByEmployeeAndDay, getSalesTotalsByEmployeeAndMonth, and getSalesTotalsByWarehouseAndMonth.


getSalesTotalsByWarehouseAndMonth

Get recent monthly sales by store (location).

This a concise data set that suits best for displaying a graph. To get a full sales report, see getSalesReport.

See also getSalesTotalsByEmployeeAndDay, getSalesTotalsByEmployeeAndMonth, and getSalesTotalsByWarehouseAndDay.


getSchedule

Returns employee's work schedule. It can be retrieved in two formats: a list of employee's working hours for each day, or a list of employee's time off.

This API call can only be used is Salon module is enabled on your account. For other salon related functions, see getEmployees and getTimeSlots.


getSessionKeyInfo

Returns creation and expire information for session key that was included in this request. To get the session user info see getSessionKeyUser


getSessionKeyUser

Returns user information for the used session key. Returned data is the same as from verifyUser verifyUser call. To get session key info see getSessionKeyInfo and to get identity token see getIdentityToken


getTimeSlots

Returns first available appointment slots for a chosen service in a selected salon (location).
API will inspect employee's schedules and find first available times that have not been booked yet.

Using this API call, you can schedule:

  • One appointment for one customer;
  • Several consecutive appointments (eg. multiple hair care services) for one customer;
  • Appointments for a group of customers who want to arrive and leave together.
This API call can only be used if Salon module is enabled on your account. For other salon related functions, see getEmployees and getSchedule.

Returns error 1044 if the service being booked does not have a default length specified in Erply backend.


getUnfinishedSales

Get a list of not completed and cancelled point of sale transactions.

This is a special integration with Berlin POS. When a sale in progress is cancelled (by clicking the red "trash can" button), the items that had been scanned so far get recorded as a "cancelled sale". If Berlin POS is configured to automatically delete pending sales at the end of a shift, these deleted documentsget recorded as "sales not completed".

This API call returns both of these records.


getUsedRewardPointRecords

Retrieve all reward point subtraction transactions.

This API call is for building custom loyalty programs. For other related calls, see addCustomerRewardPoints (to add points to a customer manually) and getEarnedRewardPointRecords (to retrieve transactions where customers have earned reward points}.

For simpler integrations, you will more likely need getCustomerRewardPoints to retrieve a customer's point balance, and subtractCustomerRewardPoints to subtract points from customer.

To edit one specific record, use editUsedRewardPointRecord. (Under normal circumstances, you should not use that method; this is only for transfering points history from one customer to another, or for correcting errors in points history. To add or remove points, use subtractCustomerRewardPoints and addCustomerRewardPoints instead.)


getSellableProducts

Returns IDs of all products that can be sold in the given location, according to product card status AND product's status in assortment (the product's status on both product card and in assortment must be "Active" or "No longer ordered").

This API call has been designed specifically for POS, and therefore it has slightly unusual behavior:

  • It returns error code 1137 (and no output) if the assortment has more than 10,000 sellable products. This is not an error condition; it just indicates that the product catalog is large enough that downloading it fully to local database would be unfeasible.
  • It returns error code 1136 (and no output) if the specified location does not have an assortment. This does not mean that it is mandatory to specify assortments for locations. On the contrary, not having an assortment means that a location may sell all products.


An assortment defines which products a particular store is allowed to sell and/or to purchase.

To retrieve a list of assortments, see getAssortments, to edit an assortment or add a new one, see saveAssortment. To manipulate with the products associated with an assortment, see API calls getAssortmentProducts, addAssortmentProducts, removeAssortmentProducts and editAssortmentProducts.

This API call is available only if "Assortments" module has been enabled on your account; otherwise, error code 1006 will be returned.


getServiceEndpointsForPOS

Returns a list of service endpoints for Berlin POS.

When called by any other API clients, returns error 1161.


getServices

This call is deprecated. Services have been phased out, and the module for managing services is no longer available on most Erply accounts. Consider using non-stock products instead of services.

Returns an array of services.


getStocktakings

Retrieve physical stocktakings.

A physical stocktaking is an operation where inventory is manually re-counted; if actual count differs from the inventory quantity in Erply, the quantity in Erply is adjusted.

When physical stocktaking is completed, the stocktaking act must be confirmed. Any surplus items can then be taken into inventory with an Inventory Registration, and missing items subtracted with an Inventory Write-Off.

To retrieve all item counts in one specific stocktaking, see getStocktakingReadings. To start a new stocktaking (create a new stocktaking act), see saveStocktaking. To update quantities on an act, see saveStocktakingReadings and incrementStocktakingReading. To delete an act, see deleteStocktaking.


getSubsidyTypes

Retrieve subsidy types.

This API call returns error 1006 if "Price list row subsidy and other fields module" is not enabled on this account.

To add new subsidy types or update existing, use the saveSubsidyType API call.
To delete subsidy types, use the deleteSubsidyType API call.


getStocktakingReadings

Retrieve item counts on one specific stocktaking act.

To retrieve a list of physical stocktakings, see getStocktakings. To start a new stocktaking (create a new stocktaking act), see saveStocktaking. To update quantities on an act, see saveStocktakingReadings (to make bulk updates) or incrementStocktakingReading (to increment quantities atomically).


getStoreRegions

Get a list of store regions.

Store regions can be used for grouping stores (locations, warehouses). The main feature of store regions is that price lists can also be applied to a region, not just individual stores, thereby simplifying price list management. A region can also have an unlimited number of price lists, unlike a location, which is limited to 5 price lists. Region can also contain customer group-specific price lists.

To edit a store region or add a new one, see saveStoreRegion. To delete a store region, see deleteStoreRegion. To manipulate with the price lists associated with a region, see API calls addStoreRegionPriceList, editStoreRegionPriceList and removeStoreRegionPriceList.

To manipulate with the price lists associated with region and customer group, see API calls addStoreRegionCustomerGroupPriceList, editStoreRegionCustomerGroupPriceList and removeStoreRegionCustomerGroupPriceList.

To see which regions a price list has been associated with, see the API call getStoreRegionsAssociatedWithPriceList.

This API call is available only if "Store regions" module has been enabled on your account.


getStoreRegionsAssociatedWithPriceList

Get a list of store regions that a price list has been associated with.

To add price lists to a region, or remove them, see API calls addStoreRegionPriceList and removeStoreRegionPriceList. To get a list of store regions, see API call getStoreRegions

For background information: in Erply, a price list always has to be associated with something to take effect. On its own, it is just a collection of prices and won't apply to any sale. A price list can be associated with:

  • Customers;
  • Customer groups.
If it has been associated with one of the above, it will apply as a "customer price list".

A price list can also be associated with any of the following:
  • Warehouses (stores, locations);
  • Store regions;
  • Customer groups in store regions.
If it has been associated with one of the above, it will apply as a "store price list".

This API call is available only if "Store regions" module has been enabled on your account.


getSummaryInventoryReport

Get summary inventory report (all stores and locations).

For more detailed data, use getProductStock instead.


getSupplierGroups

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/supplier/type.

Retrieve supplier groups.


getSupplierPriceLists

Retrieve supplier price lists and the contents of each price list.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.) Entering your supplier price lists into Erply is useful when creating Purchase Orders, or when receiving supplies; Erply will automatically populate the Price field for each item.

The following API calls help manage supplier price lists and retrieve their contents:



To search for products across all supplier price lists, see the API call getProductsFromSupplierPriceLists.


getSuppliers

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: GET /v1/supplier.

Retrieve suppliers.

Suppliers can be associated with products (see getProducts) and purchase orders / purchase invoices (see getPurchaseDocuments).


getTaxExemptions

Retrieve sales documents where tax exemption was applied. (Customer supplied a tax exemption certificate number and their tax rate for that sale was reduced.)

With this information, it is possible to build a "Tax Exemption Report".

Please note that this API call only lists those occasions where tax exemption was manually activated in POS. Sales to customers who have the "Tax Exempt" check box checked on their customer card, are NOT listed.

This API call is only available if your account has Classic back office (not Berlin back office), and you must be using at least back office version 4.5.0. Otherwise, this API call will return error code 1006.


getTaxOffices

Retrieve tax offices.


getUserGroups

This call is deprecated. We recommend to use Account Administration API instead.

The corresponding new call is: GET /v1/user-group.

Return an array of user groups.


getUserOperationsLog

Retrieve a log of all items that have been deleted from Erply (since a certain point of time). This is important for synchronizing data to a local database: getUserOperations lists items that you can delete from local database.

For more information, see the data synchronization guide: Synchronizing Data with “changedSince”


getUserRights

Returns a list of users, along with their access rights. See the saveUser for user adding or editing.


getVatRates

Retrieve the list of VAT rates (or sales tax / GST / etc. rates, depending on what taxation is used in the particular country).

To create a new tax rate, see saveVatRate.


getWarehouses

This call is deprecated. We recommend to use Account Administration API instead.

The corresponding new call is: GET /v1/warehouse.

Returns a list of warehouses, or locations, or stores.

API call getAllowedWarehouses returns the list of those warehouses that your user has access to.

To populate the drop-down list of "home stores" or "sign-up stores" on customer form, see the API call getHomeStores instead.


getCompanyTypes

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: GET /v1/customers/types.

Get a list of company types. Company types are used to specify business entity type of company client.

To edit a company type or add a new one, see saveCompanyType. To delete a company type, see deleteCompanyType.


getPersonTitles

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: GET /v1/customers/individuals/titles.

Get a list of person titles. Person titles are used as a prefix for polite client naming.

To edit a person title or add a new one, see savePersonTitle. To delete a person title, see deletePersonTitle.


getJobTitles

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: GET /v1/customers/individuals/job-titles.

Get a list of job titles. Job titles are used to specify employee's job area.

To edit a job title or add a new one, see saveJobTitle. To delete a job title, see deleteJobTitle.


incrementAttributeValue

Increment attribute value.

This API call is for editing custom objects. Erply has a custom object storage where you can store custom data for plug-ins, integrations etc.

For other object storage functions, see getObjects, saveObject, deleteObject (which allow to manipulate whole objects), and incrementAttributeValue, decrementAttributeValue — which provide a way to atomically increment or decrement one numeric field of a specific object (eg. to implement a counter).


incrementStocktakingReading

Increment a product's counted quantity on a stocktaking act.

Use this call to implement a custom scanning / counting application. The application should issue an "incrementStocktakingReading" API call for each counted item; then the totals will be correct even if multiple devices are counting and updating quantities simultaneously.

For related API calls, see getStocktakings, getStocktakingReadings and saveStocktaking.

If you want to update quantities in bulk (and your script is the only one modifiying the stocktaking, so there are no concurrency issues), you may use saveStocktakingReadings.


getExternalIdsByCustomerId

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: GET /v1/customers/external-ids.

Get all stored external IDs for customer.

New external ID can be updated or added to customer using saveCustomerExternalId call.

External ID can be removed from customer using removeCustomerExternalId call.

All external IDs can be retrieved using getAllCustomerExternalIds call.

Customer ID can be retrieved by external ID using getCustomerIdByExternalId call.


getCustomerIdByExternalId

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: GET /v1/customers/external-ids.

Get customer ID for provided external ID and integration name.

New external ID can be updated or added to customer using saveCustomerExternalId call.

External ID can be removed from customer using removeCustomerExternalId call.

All external IDs can be retrieved using getAllCustomerExternalIds call.

All external IDs for exact customer can be retrieved using getExternalIdsByCustomerId call.


getAllCustomerExternalIds

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: GET /v1/customers/external-ids.

Get all customer to external ID pairs for provided integration name.

New external ID can be updated or added to customer using saveCustomerExternalId call.

External ID can be removed from customer using removeCustomerExternalId call.

Customer ID can be retrieved by external ID using getCustomerIdByExternalId call.

All external IDs for exact customer can be retrieved using getExternalIdsByCustomerId call.


insertPosGlobalQuickButton

Insert a quick product button into a global list. Quick buttons are displayed in POS for fast access.

To change button position, see API call switchPosGlobalQuickButton.

To delete button from list, see API call deletePosGlobalQuickButton.

To retrieve list of buttons, see API call getPosGlobalQuickButtons.


insertPosStoreQuickButton

Insert a quick product button into a store-specific list. Quick buttons are displayed in POS for fast access.

To change button position, see API call switchPosStoreQuickButton.

To delete button from list, see API call deletePosStoreQuickButton.

To retrieve list of buttons, see API call getPosStoreQuickButtons.


logProcessingOfCustomerData

Add an entry to the customer data processing log.

According to the General Data Protection Regulation (GDPR), all processing done with the information of natural persons – viewing, creating, changing, deleting, transferring etc. — must be logged. API automatically writes log entries when you create, update or delete customer information. However, when you retrieve customer information from API, API does not know which records are actually used and for what purpose — therefore you are responsible for logging these processing activities yourself. You can always keep the log in the system that actually does the processing; but if that option is not available, use this API call to write log entries into Erply.

This API call must be called whenever you fetch, transfer or synchronize customer information with any of the following API calls:



If your account country is a non-EU country, error code 1149 is returned. However, if you are processing the information of EU citizens and need this functionality to be available, please notify customer support.


POSCashIN

Drop an amount of cash in register.

By convention, a cash drop with an amount of 0 is an indicator of "No Sale", ie. just opening the drawer. So if you want to record drawer openings (and have these printed on the Z Report), send a cash drop event with amount 0.

For cash payouts, use POSCashOUT. To get a list of all cash drops and cash payouts, use getCashIns.


POSCashOUT

Pay out an amount of cash from register.

For cash drops, use POSCashIN. To get a list of all cash drops and cash payouts, use getCashIns.


POSCloseDay

This call is deprecated. We recommend to use Point of Sale API instead.

The corresponding new call is: POST /v1/shift/close.

Close the day (or cashier's shift) in POS. The day must be previously opened with POSOpenDay.

To close the day, cashier needs to count the amount of cash at the register, and indicate how much of it will be stored at the register (closedSum) and how much taken away and deposited (bankedSum).

Both the opening and closing (and the amount of cash counted at opening time and closing time) will be recorded on the Z Report.

A log of POS openings and closings can be retrieved with getDayClosings.

To get a report of total payments by type, before closing the day (for reconciliation), see getPointOfSaleDayTotals.


POSOpenDay

Open the day (or cashier's shift) in POS.

To open the day, cashier needs to count the amount of cash at the register.

Day must later be closed with POSCloseDay. Both the opening and closing (and the amount of cash counted at opening time and closing time) will be recorded on the Z Report.

A log of POS openings and closings can be retrieved with getDayClosings.


POSOpenDayV2

This call is deprecated. We recommend to use Point of Sale API instead.

The corresponding new call is: POST /v1/shift/open.

V2 of the open day request. Supports shift type functionality. Open the day (or cashier's shift) in POS.

To open the day, cashier needs to count the amount of cash at the register.

Day must later be closed with POSCloseDay. Both the opening and closing (and the amount of cash counted at opening time and closing time) will be recorded on the Z Report.

To check if the day is already opened use isPOSDayOpen.


processRecurringBilling

Process recurring billing invoices.


isPOSDayOpen

This call is deprecated. We recommend to use Point of Sale API instead.

The corresponding new call is: GET /v1/shift/openlist.

Can be used to check if a day is opened for the POS or user.


recordGDPRConfirmation

Confirm that the user knows the data protection requirements of General Data Protection Regulation (a directive passed by European Parliament, taking effect in all the member states of the European Union on May 25, 2018), and agrees to follow these requirements.

This API call is part of the following process:

  1. Employee must confirm that they comply with the regulation. Employee's confirmation can be entered manually on employee form in back office, but if you want to implement some other workflow, use this API call to register the confirmation.

    A plugin is available from Erply which does just that; pops up an information box and asks employee to check a box to indicate their consent.

  2. Manager approves the employee (by clicking a button on employee form in back office).
  3. Finally, the manager can enable access restrictions from back office, Settings → Configuration, so that unapproved employees can no longer access customer information.

If extra module "Employee Consent" has not been installed on your account, error code 1006 is returned. Please contact customer support and ask this module to be installed.

If current user does not have an employee record, error code 1146 is returned.

If user has already given their confirmation, error code 1147 is returned.


redeemIssuedCoupon

This call is deprecated. We recommend to use Point of Sale API instead.

The corresponding new call is: POST /v1/giftcard/redeem/{id}.

Redeem a coupon that has been previously issued to a customer. All coupons accepted by the cashier have to be redeemed so that the coupons cannot be used again.

To just verify that a coupon is valid (before redeeming it), use verifyIssuedCoupon. To get the list of all issued coupons, use getIssuedCoupons.

redeemIssuedCoupon returns error 1040 if a coupon with such identifier has not been issued at all. If coupon has been redeemed already, API returns error 1041. If coupon has expired (and is thus not valid any more), API returns error 1045. If coupon is valid, API returns error 0.


registerReceiptPrint

Register that a receipt has been printed out from point of sale.

The printing history of one specific sales document can be retrieved with API call getPrintsForOneReceipt, a list of all receipt printings can be retrieved with API call getReceiptPrints.

This API call has been implemented to meet a specific requirement of Swedish Z Reports, and it is used by Berlin POS only on Swedish accounts. However, it is also possible to implement custom workflows if needed: you can store data with API call "registerReceiptPrint" and fetch it later with "getReceiptPrints".


removeAssortmentProducts

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/assortment/products/{ids}/bulk.

Remove products from an assortment.

An assortment defines which products a particular store is allowed to sell and/or to purchase.

To retrieve a list of assortments, see getAssortments, to edit an assortment or add a new one, see saveAssortment. To manipulate with the products associated with an assortment, see API calls getAssortmentProducts, addAssortmentProducts and editAssortmentProducts. To retrieve all products that can be sold in location according to product status in assortment and it's card see getSellableProducts.

This API call is available only if "Assortments" module has been enabled on your account.


removeInvoiceAlgorithmChange

Remove existing invoice calculation algorithm change.

To get all algorithm changes see getInvoiceAlgorithmChanges, to add a new algorithm change see addInvoiceAlgorithmChange.


removeItemsFromMatrixDimension

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: DELETE /v1/matrix/dimension/value/{ids}.

Remove variations from matrix dimension.


removeItemsFromPriceList

Remove rules from price list. You need to specify rule type and the ID of the respective product or product group that you want to remove. (If using the Quantity Discounts module, you also need to specify the "amount" parameter.)

You can specify many such parameter pairs in one API request; give a sequential number (1, 2, 3, ...) to each such pair. The "#" character below denotes this sequential number.

It is also possible to remove products from the price list, by using the deleteProductInPriceList API call.

In order to delete product rows by the row id's instead of the product id's check removePriceListProductsByRowIds.


removePriceListProductsByRowIds

Delete price list products by their row id's. In order to remove by product id's check removeItemsFromPriceList instead.


removeItemsFromSupplierPriceList

Remove rules from supplier price list.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)

You need to specify the ID of the respective product that you want to remove. (If using the Quantity Discounts module, you also need to specify the "amount" parameter.)

You can specify many such parameter pairs in one API request; give a sequential number (1, 2, 3, ...) to each such pair. The "#" character below denotes this sequential number.

If you prefer to delete prices by specifying the ID of the price list item (as opposed to product ID), see deleteProductsFromSupplierPriceList.


removeStoreRegionPriceList

Remove an association between a price list and a store region.

Store regions can be used for grouping stores (locations, warehouses). The main feature of store regions is that price lists can also be applied to a region, not just individual stores, thereby simplifying price list management. A region can also have an unlimited number of price lists, unlike a location, which is limited to 5 price lists.

To retrieve a list of regions (and price lists associated with them), see getStoreRegions. To associate a price list with a region, see addStoreRegionPriceList. To reorder region price lists, see editStoreRegionPriceList.

The price lists associated with a region will be automatically applied when making a sale from POS or creating a sales document in Erply back office, or when calling API calculateShoppingCart.

This API call is available only if "Store regions" module has been enabled on your account.


removeStoreRegionCustomerGroupPriceList

Remove an association between price list, customer group and a store region.

To retrieve a list of regions (and price lists associated with them), see getStoreRegions. To associate a price list with a region, see addStoreRegionCustomerGroupPriceList. To reorder region price lists, see editStoreRegionCustomerGroupPriceList.

The price lists associated with region and customer group will be automatically applied when making a sale from POS or creating a sales document in Erply back office, or when calling API calculateShoppingCart.

This API call is available only if "Store regions" module has been enabled on your account.


removeCustomerExternalId

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: DELETE /v1/customers/external-ids/{customerIds}.

Remove connection of external to customer ID.

New external ID can be updated or added to customer using saveCustomerExternalId call.

All external IDs can be retrieved using getAllCustomerExternalIds call.

Customer ID can be retrieved by external ID using getCustomerIdByExternalId call.

All external IDs for exact customer can be retrieved using getExternalIdsByCustomerId call.


saveCustomerExternalId

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: POST /v1/customers/external-ids/{customerId}.

Save new pair of external to customer ID mapping for provided integration. Will return 1012 error if provided external ID related to provided integration is already connected to another customer ID.

External ID can be removed from customer using removeCustomerExternalId call.

All external IDs can be retrieved using getAllCustomerExternalIds call.

Customer ID can be retrieved by external ID using getCustomerIdByExternalId call.

All external IDs for exact customer can be retrieved using getExternalIdsByCustomerId call.


saveAddress

Create or update customer's or supplier's address.

If the created or updated address belongs to a customer (to a natural person), and your account country is subject to the General Data Protection Regulation (GDPR), Erply logs the change in the customer information processing log.


saveAddressType

Create or update address type.


saveAppliance

Create or update an appliance or a vehicle. Appliances / Vehicles are related to the Assignments module.

If the Assignments module is not enabled on this account, error code 1006 is returned.

If the created or updated appliance or vehicle belongs to a natural person and your account country is subject to the General Data Protection Regulation (GDPR), Erply logs the change in the customer information processing log.


saveAssignment

Create or update an assignment.

This API call returns error 1006 if assignment module is not enabled on this account.


saveAssignmentGroup

Create or update an assignment group.

This API call returns error 1006 if assignment module is not enabled on this account.


saveAssortment

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/assortment, PUT /v1/assortment/{id}.

Add or update an assortment.

An assortment defines which products a particular store is allowed to sell and/or to purchase.

To retrieve a list of assortments, see getAssortments. To delete an assortment, see deleteAssortment. To manipulate with the products associated with an assortment, see API calls getAssortmentProducts, addAssortmentProducts, editAssortmentProducts and removeAssortmentProducts. To retrieve all products that can be sold in location according to product status in assortment and it's card see getSellableProducts.

This API call is available only if "Assortments" module has been enabled on your account.


saveBillingStatement

Set up a recurring billing.

A recurring billing indicates that customer should get a monthly (yearly) invoice for the indicated services, at the indicated price.

After the billing has been set up, recurring invoices need to be manually created and sent from back office Sales → Recurring billing, at the beginning or at the end of a month, as appropriate.

Alternatively, invoices can also be created over API with the saveSalesDocument call, and associated with the billing via the "billingStatementID" field.


saveBillingStatementReading

Creates a reading of billing statement.


saveBin

This call is deprecated. We recommend to use WMS API instead.

The corresponding new call is: POST /v1/bin.

Create or update a bin. Each bin belongs to one specific warehouse.

Bin codes must be per-warehouse unique. If you attempt to assign a duplicate code, API will return error 1012.

It is not possible to move a bin to another warehouse.


saveBinRecords

This call is deprecated. We recommend to use WMS API instead.

The corresponding new call is: POST /v1/bin-inventory-record.

Create a set of bin records. This is the recommended way to place items into bins (which have arrived with a Purchase Invoice or Inventory Registration) or remove sold items.

After saving and processing each record, API will also update the cumulative quantity of that product in that bin.

This call can also be used for editing existing records. In that case, API will also adjust the summarized quantity of that bin accordingly.

You can send multiple records with one API call; append numbers 1, 2, 3, ... to the parameter names to identify values for record 1, record 2, etc. Fore example, binID1, productID1, amount1 for the first record, binID2, productID2, amount2 for the second one and so on.

There is no hard limit to how many records you can send with one call, but it is recommended to keep it below 500. Also, more records take a longer time to process, so make sure you will not hit a timeout while waiting for API's response.


saveBrand

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/brand.

Creates or updates brand.


saveCampaign

Create or update a sales promotion.

A sales promotion is a rule that gives a discount when a certain condition is met — and can be configured to apply either automatically or be invoked manually by the cashier in POS.

For specifying unconditional discounts (that do not depend on a certain other item being purchased, or customer's total basket value), you should rather use price lists (see getPriceLists).

To retrieve promotions, see getCampaigns.

For an API call that automatically implements all promotion rules and price lists automatically for you, see calculateShoppingCart.

In order to manage the new multi warehouse links, see getCampaignWarehouses.


saveCompanyLogo

Upload company logo.


saveConfParameter

Updates configuration parameter. Returns error 1016 if parameter name is restricted or contain single or double quotes. Some configuration parameters returned by getConfParameters — 'languages', 'additionalModules', 'invoice_algorithm_version', 'default_currency' — are derived from various other settings and you cannot directly change their value.


saveCountry

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/product/country.

Creates or updates country.


saveCoupon

Create or update a coupon rule.

Coupon rule is like the "blueprint" or "type" of a printed coupon (that is issued from POS and handed to a customer). The "blueprint" specifies in what circumstances the coupons will be printed from POS, and what promotion will apply when customer returns with the coupon — ie., what discount or extra value it effectively carries.

A coupon rule should be associated with a sales promotion (see getCampaigns).

In order for the customer to use those discounts, you need to issue the customer a coupon with an unique serial number (see getIssuedCoupons, saveIssuedCoupon). When customer returns with the coupon code, it has to be scanned at the POS. Scanning redeems the coupon, invokes the promotion associated with it, and gives customer a discount.

To retrieve coupon rules, see getCoupons.


saveCurrency

Creates or updates currency.


saveCustomer

Create a new customer or update customer information. Function can be used for manipulating both companies and persons. Some parameters only apply to one or another.

If the created or updated customer is a natural person and your account country is subject to the General Data Protection Regulation (GDPR), Erply logs the change in the customer information processing log.


saveCustomerAssociation

Create a link between two customers — specify that one is an "association" for the other one.

"Associations" are a specific one-to-many, one-way relationship between customers. A customer can have zero or more "associations", each one of which is a customer in itself, and one of which can be the "default association".

To see a list of a customer's "associations", see getCustomers and pass the flag getAssociationsAndProfessionals = 1.

To delete the link between two customers, so that one ceases to be an "association" for the other one, see API call deleteCustomerAssociation.

An identical feature is "customer's professionals". See saveCustomerProfessional and deleteCustomerProfessional.


saveCustomerGroup

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: POST /v1/customers/groups.

Create or update a customer group.


saveCustomerProfessional

Create a link between two customers — specify that one is a "professional" for the other one.

"Professionals" are a specific one-to-many, one-way relationship between customers. A customer can have zero or more "professionals", each one of which is a customer in itself, and one of which can be the "default professional".

To see a list of a customer's "professionals", see getCustomers and pass the flag getAssociationsAndProfessionals = 1.

To delete the link between two customers, so that one ceases to be a "professional" for the other one, see API call deleteCustomerProfessional.

An identical feature is "customer's associations". See saveCustomerAssociation and deleteCustomerAssociation.


saveDeliveryType

Create or update a delivery type.


saveDocument

This call is deprecated. Documents module in Erply is being phased out and is no longer maintained. Although you can create the records with API call "saveDocument", there is no corresponding "getDocuments" API call to retrieve saved documents.

Create or update a document.


saveEDocuments

Creates a new EDocument (sales invoice/order or purchase invoice/order)


saveEmployee

This call is deprecated. We recommend to use Account Administration API instead.

The corresponding new call is: POST /v1/employee.

Create or update an employee.

To retrieve employees, see API call getEmployees.

To record that employee agrees to follow the data protection requirements of General Data Protection Regulation, see API call recordGDPRConfirmation.


saveEvent

Create or update an event/appointment.

In Erply backend, events (appointments) are listed in the Calendar » Tasks module.

To retrieve events, use getEvents.

Function may return error 1043 if creating appointment and employee already has an appointment in the selected time slot. (In that case you need to requery getTimeSlots and select a different start and end time for new appointment.)


saveEventType

Create or update an event type.

To retrieve event types, see getEventTypes.

Events (appointments) can be managed with the getEvents and saveEvent API calls.


saveEventStatus

Create or update an event status.

To retrieve event statuses, see getEventStatuses.

Events (appointments) can be managed with the getEvents and saveEvent API calls.


saveGiftCard

This call is deprecated. We recommend to use Point of Sale API instead.

The corresponding new call is: POST /v1/giftcard/, POST /v1/giftcard/bulk/.

Create a new gift card; or redeem an existing gift card and update its balance.

To retrieve a list of all gift cards, or for more information about gift cards in Erply, see getGiftCards.


saveInventoryRegistration

Create an Inventory Registration or update an existing one.

Inventory Registration is a document that takes products into inventory; it has a list of items and quantities. It is similar to a Purchase Invoice, but has fewer fields and is best suited for registering your initial stock quantities when you start using Erply — or for making inventory quantity adjustments.

Non-stock products and bundles cannot be on Inventory Registrations (these items do not have inventory).

Products can be removed from stock with Inventory Write-offs (see getInventoryWriteOffs and saveInventoryWriteOff) and moved between locations with Inventory Transfers (see getInventoryTransfers and saveInventoryTransfer).

To retrieve a list of Inventory Registrations, see getInventoryRegistrations.;


saveInventoryTransfer

Create or update an Inventory Transfer.

Inventory Transfer is a document that moves inventory between locations (stores); subtracts from one location and adds to the other. Inventory Transfer has a list of items and quantities.

Non-stock products and bundles cannot be transfered (these items do not have inventory).

For retrieving Inventory Transfers, see getInventoryTransfers.


saveInventoryWriteOff

Create an Inventory Write-Off or update an existing one.

Inventory Write-Off is a document that removes products from inventory; it has a list of items and quantities.

Non-stock products and bundles cannot be on Inventory Write-Offs (these items do not have inventory).

Products can be added to stock with Inventory Registrations (see getInventoryRegistrations and saveInventoryRegistration) and moved between locations with Inventory Transfers (see getInventoryTransfers and saveInventoryTransfer).

To retrieve a list of Inventory Write-Offs, see getInventoryWriteOffs.


saveInvoicePaymentType

Create or update an invoice payment method.

"Payment type" or expected payment method is an informative field on invoices. It indicates how the invoice will likely be paid by the customer. (However, keep in mind that actual payments on the invoice may be different from expected payment type.)

To list existing invoice payment methods, see getInvoicePaymentTypes.


saveIssuedCoupon

Register a printed coupon that has been issued to a customer, or update information on an existing coupon.

Issued coupon must have a unique identifier. Since coupons may carry monetary value, Erply keeps track of issued coupons and allows to validate (verify) a coupon when customer comes to redeem it.

The recommended workflow is as follows:

  1. Register a printed coupon with saveIssuedCoupon.
  2. When customer returs to the store to redeem the coupon, use API verifyIssuedCoupon to check that the coupon is valid (ie. the coupon exists in the system, has not been redeemed yet, and has not expired).
  3. Call redeemIssuedCoupon to redeem the coupon, so that it could not be used twice.

To retrieve coupons, use API call getIssuedCoupons.

saveIssuedCoupon also allows you to update the attributes of an existing coupon. DO NOT use it for marking a coupon as redeemed — there is a separate call, redeemIssuedCoupon, that you should use for that. Only use saveIssuedCoupon if you want to update coupon's expiry date or edit how it was purchased or who redeemed it (customer name, store, employee, etc.)

A coupon may have a "printing cost" — if the coupon is issued, a certain amount of reward points is subtracted from customer's point balance. This is done automatically by the API. However, if customer does not have a sufficient amount of points, the coupon does not get issued and API returns error 1042 instead.


saveLocationInWarehouse

Create or update location in warehouse.

"Location in warehouse" is a product classifier. A product can have one "location in warehouse".

See also getLocationsInWarehouse and deleteLocationInWarehouse.


saveMasterListProducts

Import a set of products into Master List, creating new products or updating existing ones.

You can create or update 1000 products at a time. To use this API call, configuration parameter "master_list_unique_field" must be defined. This parameter identifies which field contains a unique code and should be used for identification and matching. By default "code". The field must be one of the code fields.

For other Master List-related API calls, see findMasterListProducts and copyMasterListProductsToErply.


saveMatrixDimension

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/matrix/dimension.

Create a matrix dimension, or add values to an existing dimension.

A matrix dimension is necessary for setting up matrix products. Typical matrix dimensions are, for example, "Size" (in which the values might be 2, 4, 6, 8 — or S, M, L, XL) and "Color" (which may contain Blue, Red, Black, Green etc).

Different matrix products can share the same dimensions, and a matrix product does not need to have variations corresponding to each value in the dimension. For example, it is sufficient to have just one dimension for all letter sizes, one for all numeric sizes and one for all kinds of colors.

Matrix products and their variations can be created with API call getProducts.

This API call is the best choice if you want to create a brand new dimension with a specific set of values. However, if a dimension already exists and you want to modify its list of values, see the following API calls instead:

API call "saveMatrixDimension" can be used to update the list of values, too, but it is recommended to not rely on that behavior. If you specify an existing dimension's ID and a list of values, API tries to look up existing values by name (the lookup is case-insensitive). If a match is found, the code of the found value is updated; the name is not. If no match is found, a new value will be inserted.

Hence, if you have an existing dimension "Color", with values "GREEN" and "RED", and call saveMatrixDimension with the following parameters:
dimensionID = ...
valueName1 = "Green"
valueCode1 = "123"
valueName2 = "Blue"
valueCode2 = "124"
the result will be as follows:
  • The code of color "GREEN" will be updated to "123". The name stays unchanged.
  • A new color, "Blue", with code "124", will be added.
Considering that this API call does not report which values were matched to existing ones and which ones were added as new, it is more reliable to use addItemToMatrixDimension and editItemInMatrixDimension instead.


saveObject

Create or update an object.

Erply has an object storage where you can store custom data for plug-ins, integrations etc.

For other object storage functions, see getObjects, saveObject, deleteObject (which allow to manipulate whole objects), and incrementAttributeValue, decrementAttributeValue — which provide a way to atomically increment or decrement one numeric field of a specific object (eg. to implement a counter).


savePayment

Create or update a payment.

In Erply, a payment is associated with a customer, and optionally an invoice (or some other sales document, eg. a sales order). One invoice can have many payments. Payment, on the other hand, can only be associated with one invoice at a time. If customer makes an aggregate payment towards several invoices, it needs to be split up into parts.

If a payment is not associated with any sales document, it represents a deposit (a prepayment, customer's store credit) and can be used to pay off unpaid invoices.

To list payments, see getPayments.

A typical use case for the savePayment API call is recording a sale (that has been made in POS or in a web shop). In that case, send a saveSalesDocument API call, followed by savePayment.

See also calculateShoppingCart. That API call helps you calculate cart total, and also gives instructions regarding other retail features (issuing and redeeming coupons etc.)
To make savePayment calls idempotent, use the "temporaryUUID" field.


savePaymentType

Create or update a payment type.

To retrieve existing payment types, see getPaymentTypes.


savePriceList

Create a price list, or add prices to an existing price list.

A price list can contain three types of rules: 1) fixed prices for specified products, 2) fixed prices for specified services, 3) percentage discounts for product groups. You may specify as many rules of each type as necessary.

If you need to create a very large price list (with thousands of items), we strongly recommend to create it in parts — create the list itself with the first API call, and then add items into the list with each subsequent call, eg. in batches of 1000.

If needed, you can edit just an existing price list's name, status and validity dates. In that case, API will not modify price list contents. However, you can also use this call for adding or updating prices in an existing price list. If you send any price list rules, API will check if the specified product or product group already exists in price list. If yes, that price list item will be updated. If not, a new one will be added.

If you want to remove any items from the price list, use the removeItemsFromPriceList or the deleteProductInPriceList API call.

It is also possible to add new items to the price list with the addProductToPriceList API call or edit a single rule with the editProductInPriceList API call.

If you have the Quantity Discounts module enabled, please note that each product may have multiple entries in the price list. If you want to address and update one specific rule, you also need to pass along the "amount" parameter.


saveProduct

Create or update a product.

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


saveProductCategory

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/product/category.

Create or update a product category.


saveProductFile

Attach a new file (manual, brochure, price list, spec sheet) to product card, or replace an existing file.

To retrieve a list of files attached to a product, call getProducts and see the element "relatedFiles".

For an identical call which does not require the file parameter to be base64-encoded, seee saveProductFile2.


saveProductFile2

Attach a new file (manual, brochure, price list, spec sheet) to product card, or replace an existing file.

To retrieve a list of files attached to a product, call getProducts and see the element "relatedFiles".

This call is identical to saveProductFile, but the input parameter file takes the file's contents in raw binary format (unlike saveProductFile which requires it to be base64-encoded).


saveProductGroup

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/product/group.

Create or update a product group.


saveProductPackage

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/product/package.

Add a package option (eg. "a box of 12" or "a pallet of 2500") to a product, or modify an existing one.

In back office, packages are listed in the subsection Packages on product card.

To get a list of packages for a product (and their IDs, to be able to modify them), call API getProducts and specify flag getPackageInfo = 1.

To delete a package, see deleteProductPackage.


saveProductPicture

Attach a new picture to a product, or replace an existing picture.

To retrieve a list of images attached to a product, call getProducts and see the element "images". To remove a picture, use deleteProductPicture.

For an identical call which does not require the picture parameter to be base64-encoded, seee saveProductPicture2.


saveProductPicture2

Attach a new picture to a product, or replace an existing picture.

To retrieve a list of images attached to a product, call getProducts and see the element "images". To remove a picture, use deleteProductPicture.

This call is identical to saveProductPicture, but the input parameter picture takes the file's contents in raw binary format (unlike saveProductPicture which requires it to be base64-encoded).


saveProductPriorityGroup

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/product/priority/group.

Create or update priority group.


saveProductUnit

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/product/unit.

Create or update product unit.


saveProject

Create or update a project.


savePurchaseDocument

Create a new purchase invoice, purchase order or purchase return, or update an existing one.

To update document row prices see API call updatePurchaseDocumentRows.

To update additional costs see API call updatePurchaseDocumentAdditionalCosts.
To make savePurchaseDocument calls idempotent, use the "temporaryUUID" field.


updatePurchaseDocumentAdditionalCosts

Update purchase document additional costs.


updatePurchaseDocumentRows

Update purchase document row prices. This call makes adjustments to existing rows and does not replace, add or remove any rows. Also works on confirmed documents.


saveSalesDocument

Create a new sales document (invoice, sales order, etc.) or update an existing one.

Sales documents in Erply have a header with general information (customer, date etc.) and one or more lines that list the items, quantities and prices.

Every sales document in Erply needs to be confirmed. When confirmed, a sales invoice, for example, 1) receives a number, 2) generates sales revenue and VAT / tax obligation and 3) removes sold items from inventory. A confirmed sales order places a reservation on ordered items. A confirmed document may not be fully editable any more, or you might need special user rights for some kinds of changes.

Possible sales document types are listed below. Most common ones that you'll probably need, are:

  • INVWAYBILL (this is an ordinary sales invoice),
  • CASHINVOICE (basically the same, but the printout is formatted as a POS receipt),
  • ORDER (a sales order).
List of sales documents can be retrieved with getSalesDocuments. If you are making a sale, but you first need to know up-to-date prices and correct tax (VAT) rates for the items customer has selected, and get invoice total, see calculateShoppingCart. To apply a payment to the sale, use savePayment.

If the sales document that you created or updated is associated with a customer who is a natural person — and if your account country is subject to the General Data Protection Regulation (GDPR) — Erply logs the sale in the customer information processing log.

To make saveSalesDocument calls idempotent, use the "temporaryUUID" field.


saveService

This call is deprecated. Services have been phased out, and the module for managing services is no longer available on most Erply accounts. Consider using non-stock products instead of services.

Create or update a service.


saveStocktaking

Create or update a physical stocktaking act.

Creating the act is the first step in physical stocktaking. Next, it must be filled with quantities counted in the warehouse. After all quantities have been recorded and verified, the act must be confirmed. Finally, surplus quantities should be taken into stock with an Inventory Registration and missing quantites written off with an Inventory Write-off. Note that just confirming the act will not update your inventory yet!

Inventory Registrations and Write-offs can be created manually in Erply back-end.

For related API calls, see getStocktakings, deleteStocktaking, getStocktakingReadings, saveStocktakingReadings and incrementStocktakingReading.


saveStocktakingReadings

Update product count on a physical stocktaking sheet.

Note! This API call should be used only in single-client mode (if your API script or application is the only one updating the quantities). If you have several applications that need to update quantities simultaneously, use incrementStocktakingReading instead.

For related API calls, see getStocktakings, getStocktakingReadings and saveStocktaking.


saveStoreRegion

Add or update a store region.

Store regions can be used for grouping stores (locations, warehouses). The main feature of store regions is that price lists can also be applied to a region, not just individual stores, thereby simplifying price list management. A region can also have an unlimited number of price lists, unlike a location, which is limited to 5 price lists.

To retrieve a list of store regions, see getStoreRegions. To delete a store region, see deleteStoreRegion. To manipulate with the price lists associated with a region, see API calls addStoreRegionPriceList, editStoreRegionPriceList and removeStoreRegionPriceList.

This API call is available only if "Store regions" module has been enabled on your account.


saveSubsidyType

Create or update a subsidy type.

API user must have the rights to manage Subsidy types.

This API call returns error 1006 if "Price list row subsidy and other fields module" is not enabled on this account.
It is required to add at least one name parameter. It can be either the general "name" parameter or any of the name parameters with a language code (e.g. "nameENG").

To find subsidy types, use the getSubsidyTypes API call.
To delete subsidy types, use the deleteSubsidyType API call.


saveSupplier

This call is deprecated. We recommend to use PIM API instead.

The corresponding new call is: POST /v1/supplier.

Create or update a supplier.


saveSupplierGroup

Create or update a supplier group.


saveSupplierPriceList

Create supplier price list, or add prices to an existing price list.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)

If you need to create a very large price list (with thousands of items), we strongly recommend to create it in parts — create the list itself with the first API call, and then add items into the list with each subsequent call, eg. in batches of 1000.

If needed, you can edit just an existing price list's name, status, validity dates and supplier. In that case, API will not modify price list contents. However, you can also use this call for adding or updating prices in an existing price list. If you send any price list rules, API will check if the specified product already exists in price list. If yes, that price list item will be updated. If not, a new one will be added.

If you want to remove any items from the price list, use the removeItemsFromSupplierPriceList API call.

If you have the Quantity Discounts module enabled, please note that each product may have multiple entries in the price list. If you want to address and update one specific rule, you also need to pass along the "amount" parameter.


deleteSupplierPriceList

Delete an existing supplier price list or price lists.

Contact Erply Helpdesk to enable Supplier Price Lists module on your account. (If not enabled, API returns error 1006.)


saveUser

Create or update a user. See the getUserRights with userID field for user data and rights retrieving. Newly created user will have access to all warehouses, if some specific list is of warehouses is required for user it can be specified using warehouseIDs parameter (will replace existing list of access rights).

This API call may return error 1061 or 1062 (if you do not have the right to add/edit users) or 1066 (if you do not have the right to manage users in that specific user group).


saveUserOperationsLog

Write a custom log entry in user activity log.

User activity log is displayed in Erply backend, in Settings » Log of deleted items. As the name suggests, the log is mostly used for tracking deleted records. We strongly recommend to check with Erply development team before using the log for custom purposes.

Logs can be queried with getUserOperationsLog, but functionality is currently limited.


saveWarehouse

This call is deprecated. We recommend to use Account Administration API instead.

The corresponding new call is: POST /v1/warehouse.

Create or update a store (location, warehouse). Access right to newly created store will be given to creator only. If its require to give access to newly created store for all existing users, specify addAccessForAllUsers = 1

To retrieve a list of locations, see getWarehouses.


saveVatRate

Create or update a VAT rate (or sales tax / GST / etc. rate, depending on what taxation is used in the particular country).

To get a list of all tax rates, see getVatRates.


saveVatRateComponent

Create or update a component of VAT rate (or sales tax / GST / etc. rate, depending on what taxation is used in the particular country).

To delete tax component, see deleteVatRateComponent.

The following call can be used only if the "City, county and state tax rates" module has been enabled on your account.


saveCompanyType

Add or update company type. Company types are used to specify business entity type of company client.

To retrieve a list of company types, see getCompanyTypes. To delete a company type, see deleteCompanyType.


savePersonTitle

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: POST /v1/customers/individuals/titles.

Add or update person title. Person titles are used as a prefix for polite client naming.

To retrieve a list of person titles, see getPersonTitles. To delete a person title, see deletePersonTitle.


saveJobTitle

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: POST /v1/customers/individuals/job-titles.

Add or update job title. Job titles are used to specify employee's job area.

To retrieve a list of job titles, see getJobTitles. To delete a job title, see deleteJobTitle.


saveBusinessArea

This call is deprecated. We recommend to use CRM API instead.

The corresponding new call is: POST /v1/business/areas.

Add or update business area. Business areas are used to specify area of company client.

To retrieve a list of business areas, see getBusinessAreas. To delete a business area, see deleteBusinessArea.


sendByEmail

A request for sending a document or report by email. This API call is synchronous (returns when email is sent) and can take a few seconds to complete. Sending will be handled by the server. Email subject, sender's address, message content and attachment format (HTML/PDF) will be decided serverside and are configurable from Erply settings.


sendToPrint

This call is deprecated. This API call does not do anything useful any more.

Deprecated.


setExcisesToPurchaseDocuments

Copy the current excises from the product card to purchase document rows.

This API call returns error 1006 if Alcohol Wholesaling module is not enabled on this account.


subtractCustomerRewardPoints

Subtract, or "redeem", customer's reward points.

Reward points accrue automatically from customer's purchases. But whenever you perform an action that needs reward points to be redeemed — eg. apply a sales promotion where customer trades points for discount — you need to subtract the point amount manually, by calling subtractCustomerRewardPoints.

Use getCustomerRewardPoints to query for customer's current amount of points.

To add points manually (although you typically do not need to do that), see addCustomerRewardPoints. If you are building a custom loyalty program, you may also take a look at getEarnedRewardPointRecords and getUsedRewardPointRecords — to retrieve a detailed list of all transactions where customer has earned or spent points.

Points are also subtracted from customer's balance when you issue a coupon that "costs" reward points (see saveIssuedCoupon). However, this is done automatically by the API, and you do not need to call subtractCustomerRewardPoints for that.


setOAuthConfiguration

This API call is used for verifyOAuthToken and createUserFromOAuthToken configuration storing. Data can be retrieved using call getOAuthConfiguration. If provided data is not a valid JSON error 1014 will be returned.

Here is the intended use case explained in more detail.


setSalesOrderAsFulfilled

Change the status of one specific sales order to "fulfilled".

To change a sales document's status or any other properties, you can also use the more general API call, saveSalesDocument. The point of "setSalesOrderAsFulfilled" is that it does not require the user to have the permission to modify sales orders.

Updating a sales order's status to "fulfilled" is commonly one part of a point-of-sale transaction, but store manager may not want to give the cashiers the full authority to edit all sales orders. The point-of-sale application, however, does not need to do nothing else with the order — it just needs to update its status to "fulfilled". Therefore, we have exposed this operation as a separate API call.

This API call returns error code 1011 if the supplied ID does not belong to a sales order.


setStocktakingUncountedProductsToDefault

Find all products on the stocktaking that are uncounted (the counted quantity is empty), and set their count equal to total quantity in stock or available quantity (depending on stocktaking settings).


setStocktakingUncountedProductsToZero

Find all products on the stocktaking that are uncounted (the counted quantity is empty), and set their count to 0.


switchPosGlobalQuickButton

Switch two quick product buttons in a global list. Quick buttons are displayed in POS for fast access.

To delete button from list, see API call deletePosGlobalQuickButton.

Insert new button into the list, see API call insertPosGlobalQuickButton.

To retrieve list of buttons, see API call getPosGlobalQuickButtons.

API will return error 1013 without specified field if first and second buttons are the same.


switchPosStoreQuickButton

Switch two quick product buttons in a store-specific list. Quick buttons are displayed in POS for fast access.

To delete button from list, see API call deletePosStoreQuickButton.

Insert new button into the list, see API call insertPosStoreQuickButton.

To retrieve list of buttons, see API call getPosStoreQuickButtons.

API will return error 1013 without specified field if first and second buttons are the same.


switchUser

This is an authentication function. When called, it provides you a "session key" that you can use in subsequent API calls as a token of authentication.

switchUser allows you to log in with user PIN (no user name / password needed); however, this API call can only be used for "user switching". It means that for calling switchUser, you need to already have a valid session key (or one that has just expired, no more than 2 hours old).

For a more general authentication function (that you should be using in most cases!), see verifyUser. It requires a user name and password. In verifyUser documentation, you will also find a general introduction to API authentication and sessions.

Successful user switch will give you a NEW session key, with the user rights of the PIN holder.

If authentication does not succeed, switchUser returns error 1051 or 1052. If the supplied session key is invalid, API returns error 1054 or 1055. If the session key is too old, API returns error 1056. In case of a success, API returns the information described below.


syncTotalProductStock

Get each product's total inventory quantity across all locations.

If you don't specify "changedSince" parameter, then all the products that have stock different from 0 will be returned. Otherwise, this API call will return the total stock of products whose stock has changed after the specified time.

If you add parameter "getAmountReserved = 1", then API will return the reserved amounts as well. When product's stock is 0 but reserved amount is different from 0, then these products will also be returned. Input parameter "changedSince" takes into account the reservations as well if you have specified "getAmountReserved" parameter.


updateBinStatus

Archive or de-archive a bin, or multiple bins simultaneously. API prevents archival if a bin still has quantities in it.


updatePrices

Update price on product card, for many products simultaneously.

This API call is specifically for updating product card price, but any other mass updates can be done by making API calls in bulk.

For editing product card in general, see saveProduct.


validateCustomerUsername

Validate customer's web shop user name. API checks that the provided user name is unique — no other customer has such user name yet. If user name is not unique, API returns error 1012, otherwise error code 0 (success).

Use this API call before you assign a web shop user name and password to a customer (API call saveCustomer, fields username and password).


verifyCustomerUser

Validate customer's web shop user name and password.

This API call is for building a web shop that has a log-in (members-only) area. In Erply Customer module, you can assign a user name and password for each of your customers. (These user names / passwords DO NOT grant the customer any access into your Erply account, and cannot be used for that purpose. They can only be used in your web shop.)

Use API verifyCustomerUser to validate the user name and password and retrieve the customer record that these credentials belong to. Calling This API call will not create any "session" or make the customer somehow logged into API; it just serves a verification purpose.

Instead, if you want to learn how to generally authenticate yourself when connecting to Erply API — to be able to issue any API calls at all — see verifyUser.


getIdentityToken

Returns JWT from Erply identity for the current session. This can be used to authenticate with various Erply services that require a JWT.

A session is connected to a single JWT. When one does not exist for the session then a new one will be created with the same lifetime as the session.

A single JWT can be connected to multiple sessions - this means the returned JWT does not always have the same lifetime as the session (lifetime of the JWT is connected to the session that created it initially - use verifyIdentityToken to get that session).

To switch a JWT to session or to get the session that has the same lifetime as the token then use verifyIdentityToken.

Here is the intended use case explained in more detail.


getJwtToken

Returns JWT from Erply API. This can be used to authenticate with various Erply services that require a JWT. Can only be used with registered partners. When using a sessionKey to generate one then its lifetime will match that of the sessions.

Here is the intended use case explained in more detail.


verifyIdentityToken

This API call is used to sign into back office through Launchpad. It verifies if the Json Web Token is correct, Erply account is integrated with Identity and creates a new session. An error is returned if user doesn't exist in Erply or hasn't been assigned to a user group.

A JWT is always connected to a single session.

As long as the session is valid then the same one will be returned with this call. If a session does not exist or has expired then a new one will be created with the same lifetime as the JWT.

Alternatively a session key can be used to retrieve the JWT with getIdentityToken.

Here is the intended use case explained in more detail.


verifyOAuthToken

This API call is used to log into Erply API using signed tokens. This call is used for single sign-on integration, we accept user data containing token for logging into Erply, this token will be validated using public key server.

If required configuration is missing or contains incorrect format errors 1187 or 1188 will be returned, configuration data can be set using setOAuthConfiguration call.

If token parsing failed error 1191 will be returned.

If token doesnt contain required information error 1172 will be returned.

If no user exist to match with provided data error 1173 will be returned, user can be created from same tokens using createUserFromOAuthToken call.

If user "roles" cannot be matched with any Erply user group error 1059 will be returned, token can change or assign user group according to mapping stored in configuration, see setOAuthConfiguration call.

Here is the intended use case explained in more detail.


verifyIssuedCoupon

Validate a coupon identifier. The function verifies that the coupon has indeed been issued previously (using saveIssuedCoupon), that it has not expired, and that it has not been redeemed yet (using redeemIssuedCoupon).

If coupon has not been issued, returns error 1040. If coupon has been redeemed already, returns error 1041. If coupon has expired, returns error 1045. If coupon is valid, returns error 0.


verifyUser

Log into Erply API: authenticate yourself with a user name and password.

Each communication session with Erply API must begin with a call to verifyUser. Successful log-in will give you a session key; include it with every subsequent API call. (Send it as input parameter "sessionKey").

By default, session will last for one hour. When session expires, all API calls will start returning a 1054 or 1055 error; this is an indication that you should call verifyUser again to receive a fresh session key.

We recommend that you build authentication and session keep-alive into your API wrapper class — so that it automatically refreshes session key when it is about to expire, and is able to re-authenticate and re-issue an API call if it receives error 1054/1055.

If logging in does not succeed, verifyUser returns error 1050, 1051 or 1052. To get session user info without creating a new session see getSessionKeyUser


createInstallation

Create a new Erply account.


createUserFromIdentityToken

Create a new user to Erply. If username with the email address that's in Json Web Token already exists in Erply then an error is returned.

Here is the intended use case explained in more detail.


createUserFromOAuthToken

Create a new user to Erply using signed tokens. This call is used for single sign-on integration, we accept user data containing token for logging into Erply, this token will be validated using public key server.

If required configuration is missing or contains incorrect format errors 1187 or 1188 will be returned, configuration data can be set using setOAuthConfiguration call.

If token parsing failed error 1191 will be returned with related field name.

If token does not contain required information error 1172 will be returned.

If user already exist error 1175 will be returned.

If user "roles" cannot be matched with any Erply user group error 1059 will be returned.

Here is the intended use case explained in more detail.


updateProductModificationTimestamp

Update products changed timestamp to current time and changed by to current user.


getPromotionTiers

Get a list of promotion tiers. Promotion tiers are used to specify promotion execution order and ability to disable some promotions with manual discount reason codes.

To delete a promotion tier see API call deletePromotionTier.

To add new promotion tier see API call insertPromotionTier.

To update existing promotion tier see API call updatePromotionTier.

To change promotion tier position in the list see API call movePromotionTier.


insertPromotionTier

Add new promotion tier. Promotion tiers are used to specify promotion execution order and ability to disable some promotions with manual discount reason codes.

To get list of all promotion tiers see API call getPromotionTiers.

To delete a promotion tier see API call deletePromotionTier.

To update existing promotion tier see API call updatePromotionTier.

To change promotion tier position in the list see API call movePromotionTier.


updatePromotionTier

Update existing promotion tier. Promotion tiers are used to specify promotion execution order and ability to disable some promotions with manual discount reason codes.

To get list of all promotion tiers see API call getPromotionTiers.

To delete a promotion tier see API call deletePromotionTier.

To add new promotion tier see API call insertPromotionTier.

To change promotion tier position in the list see API call movePromotionTier.


deletePromotionTier

Delete existing promotion tier. Promotion tiers are used to specify promotion execution order and ability to disable some promotions with manual discount reason codes.

To update existing promotion tier see API call updatePromotionTier.

To add new promotion tier see API call insertPromotionTier.

To change promotion tier position in the list see API call movePromotionTier.


movePromotionTier

Move promotion tier before or after selected order. Promotion tiers are used to specify promotion execution order and ability to disable some promotions with manual discount reason codes.

To update existing promotion tier see API call updatePromotionTier.

To add new promotion tier see API call insertPromotionTier.

To delete a promotion tier see API call deletePromotionTier.


getIPWhitelistSettings

Get currently saved IP whitelisting settings. Use saveIPWhitelistSettings to edit the settings.


saveIPWhitelistSettings

Save IP whitelisting settings. NOTE: All IP entries will be saved as is. Any existing ones that are not saved here will be removed.

Its recommended to check with getIPWhitelistSettings before save what currently is saved and adjust the saved ips accordingly.


updateSalesDocumentRowTotals

Recalculate and update invoice row totals.