List of webstore related API requests

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.

---

getMatrixDimensions

Returns an array of possible matrix dimensions.

---

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)

---

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

---

getBrands

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

---

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.

---

getProductUnits

Returns an array of product units.

---

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.

---

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.

---

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.

---

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.

---

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.

---

getAddresses

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.

---

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.

---

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.

---

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.

---

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.

---

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.

---