List of sales related API requests

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.

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.

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.

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.

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.

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.

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

getProjects

Returns an array of projects.

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

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.

getCurrencies

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

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.

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.

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.

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.

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.

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.

deleteSalesDocument

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

deletePayment

Delete a payment.