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.

Input parameters

Parameter name Description Possible value Required
id  Search for a specific sales document by ID.  Integer    
ids  Multiple sales document IDs, separated by commas, such as: 1,2,3,4,5.  String    
clientID  Search for invoices by customer ID.  Integer    
clientIDs  Multiple customer IDs, separated by commas, such as: 1,2,3,4,5.  String    
clientName    String    
employeeID  Search for invoices created by this employee.  Integer    
warehouseID  Search for invoices by warehouse ID.  Integer    
pointOfSaleID  Search for invoices by point of sale ID.  Integer    
projectID  Search for invoices by project ID.  Integer    
productID  Search for invoices by product ID.  Integer    
payerID 

Filter invoices by payer. You can only use this filter if you have a "Payer" field on your back office invoice form — this depends on your account settings.

Note that setting the payer is not required, so this field may be empty on invoices.

 
Integer    
shipToID 

Filter invoices by the recipient of goods. You can only use this filter if you have a "Ship To" field on your back office invoice form — this depends on your account settings.

Note that setting the recipient is not required, so this field may be empty on invoices.

 
Integer    
confirmed  If this parameter is supplied, returns either only confirmed, or only non-confirmed sales documents.  0 or 1    
number  Search for a sales document by number.
Please note that sales documents of different types may have the same numbers (eg. there might be an Order 100001 as well as an Invoice-Waybill 100001), so in some cases you might want to set the type filter as well.

By default, this field only searches for sales documents by their regular number. If you have assigned custom numbers to your sales documents (numbers that may contain letters and other characters, see saveSalesDocumentcustomNumber), you can enable configuration parameter search_invoice_by_regular_and_custom_number = 1, so that both fields would be searched simultaneously. 
Integer    
numberOrCustomer  Search by invoice number, customer name, e-mail, phone, cellphone or customer loyalty card #. API searches only from the beginning of each field.

Note that this only searches from regular invoice numbers, not custom ones. 
String    
referenceNumber  Search by reference number.  String    
dateFrom    Date (yyyy-mm-dd)    
dateTo    Date (yyyy-mm-dd)    
deliveryDateFrom  Search by deliveryDate field - customer requested delivery date for whole document.  Date (yyyy-mm-dd)    
deliveryDateTo  Search by deliveryDate field - customer requested delivery date for whole document.  Date (yyyy-mm-dd)    
rowDeliveryDateFrom  Search by deliveryDate field in document rows - customer requested delivery date for one specific item.  Date (yyyy-mm-dd)    
rowDeliveryDateTo  Search by deliveryDate field in document rows - customer requested delivery date for one specific item.  Date (yyyy-mm-dd)    
type  INVWAYBILL, CASHINVOICE, WAYBILL, PREPAYMENT, OFFER, EXPORTINVOICE, RESERVATION, CREDITINVOICE, ORDER, or INVOICE  String    
types  You can specify multiple document types, separated by commas.  String    
nonReturnedItemsOnly  If set to 1, fetches only those sales documents which have not been fully voided/returned/credited.

If a sales document has been partially credited, returns only those amounts and rows that have not been credited yet. 
0 or 1    
searchAttributeName#
searchAttributeValue# 
Search for sales documents that have a custom attribute with a specific value. You need to specify the name of the attribute as well as the required value. API lets you set multiple such filters; first pair of input parameters should be searchAttributeName1 and searchAttributeValue1, second pair should be searchAttributeName2 and searchAttributeValue2 etc. In other words, replace "#" with 1, 2, 3, ... .  String    
getRowsForAllInvoices  If this parameter is specified, response always includes the rows (lines) of each sales document (not just the header), regardless of whether the search returned one or many results. Rows are contained in attribute "rows".  0 or 1    
getCustomerInformation  If this parameter is specified, response will always include customer, payer and ship to data.  0 or 1    
getReturnedPayments  If set to 1, API also returns returned payments for selected sales documents.      
getAddedTimestamp  If set to 1, API also returns sales invoice creation timestamp.  Unix timestamp.    
dueDateFrom    Date (yyyy-mm-dd)    
dueDateTo    Date (yyyy-mm-dd)    
unpaidItemsOnly  If set to 1, API returns only unpaid sales documents.      
getCOGS  If set to 1, API also returns the cost of goods sold.      
getUnfulfilledDocuments  If set to 1, API returns only unfulfilled documents.      
invoiceState  PENDING, READY, MAILED, PRINTED, SHIPPED, FULFILLED, CANCELLED or NOT_CANCELLED (returns all documents except cancelled ones)  String    
assignmentID    Integer    
excludeGiftCards  If set to 1, API will not return invoice rows that contain a gift card. This is useful for implementing a rule in POS that gift cards cannot be returned. When a customer is doing a return with receipt, and cashier calls up the original receipt to select items to be retuned, gift cards will not be listed.  0 or 1    
changedSince  Retrieve only items that have been added or modified since the specified timestamp. Use it to keep a local database in sync with ERPLY.  Integer (Unix timestamp)    
lang  Retrieve item names in a specific language. If omitted, API will return item names in the default language of your ERPLY account.
Possible values:
  • 'eng' - English
  • 'spa' - Spanish
  • 'ger' - German
  • 'swe' - Swedish
  • 'fin' - Finnish
  • 'rus' - Russian
  • 'est' - Estonian
  • 'lat' - Latvian
  • 'lit' - Lithuanian
  • 'gre' - Greek
 
String    
orderBy    'dateAndNumber', 'clientName', or 'lastChanged'. By default 'dateAndNumber'    
orderByDir    Ordering direction, 'asc' or 'desc'. By default 'desc'    
recordsOnPage  Number of records API should return. By default 20, at most 100.  Integer    
pageNo  API returns at most recordsOnPage items at a time. To retrive the next recordsOnPage items, send a new request with pageNo incremented by one. By default, API returns "page 1".  Integer    

Response

Field name Type Description
id  Integer  invoice ID  
type  String  INVWAYBILL, CASHINVOICE, WAYBILL, PREPAYMENT, OFFER, EXPORTINVOICE, RESERVATION, CREDITINVOICE, ORDER or INVOICE  
exportInvoiceType  String  Used only if document type is EXPORTINVOICE. Value: EU or NOTEU  
currencyCode  String  Currency code: EUR, USD.  
currencyRate  Decimal  eg. 1.25543
Exchange rate of the invoice currency against system's default currency.  
warehouseID  Integer  ID of the warehouse from which goods are sold.  
warehouseName  String  Name of the warehouse.  
pointOfSaleID  Integer  Point of sale ID.  
pointOfSaleName  String  Point of sale name.  
pricelistID  Integer    
number  String    
date  Date  eg. 2010-01-29  
inventoryTransactionDate  Date  Inventory transaction date.
This is the date on which the document was confirmed and when the items on this document were added into inventory, or removed from inventory. While "document date" can be edited by users at any time, "inventory transaction date" is always set by ERPLY and cannot be changed.
Inventory Reports and COGS reports are based on the inventory transaction date.  
time  Time  eg. 14:59:00  
clientID  Integer 

Customer ID. Each invoice is always associated with a customer. See getCustomers.

Please note that the semantic meaning of "customer" may differ from one account to another. On older accounts, the "Customer" effectively means "recipient of goods", and it is additionally possible to define a "payer", but this is not required. (If not set, then the specified customer is both the payer as well as the recipient.)

On newer accounts, the "Customer" effectively means "payer", and it is possible to define a recipient (field "Ship to"), but this is not required. Hence, the roles have been reversed.

This will affect you if you have a standard integration used on multiple accounts, and you need to be able to set both payers and recipients. At the moment there is no way to process the output of getSalesDocuments with the same approach on all accounts; you need to inspect account configuration and tailor your processing logic accordingly.

Call getConfParameters and check the value of configuration parameter "invoice_client_is_payer".

If it is 1, then:

  • Payer can be found from the field clientID;
  • Recipient, if it has been specified, can be found from the field shipToID.

If the value of the parameter is 0 or it has not been defined, then:

  • Recipient can be found from the field customerID;
  • Payer, if defined, can be found from the field payerID.

Fields "addressID", "payerAddressID" and "shipToAddressID" should be interpreted according to the same pattern.

Future API versions may get a uniform way of addressing recipients and payers.

 
clientName  String  Customer name.  
clientEmail  String  Customer e-mail address.  
clientCardNumber  String  Code of customer's loyalty/membership card. This corresponds to the "customerCardNumber" field in API call getCustomers.  
addressID  Integer  ID of customer's address on this invoice.  
address  String  Customer's address — full address, formatted.  
clientPaysViaFactoring  Integer (0 or 1)  Indicates this customer pays invoices via factoring. (This is a flag you can set on customer card.)  
payerID  Integer 

This field only appears if your account has a "Payer" field on invoice form. See the longer explanation above.

Invoice payer ("Bill To") — if different from the receiver of goods.

If payer and recipient are the same, the "Payer" field in ERPLY is typically left empty, and fields "payerID", "payerName", "payerAddressID", "payerAddress", "payerPaysViaFactoring" in API output will not contain any values.

 
payerName  String 

Invoice payer name.

This field only appears if your account has a "Payer" field on invoice form. See the longer explanation above.

 
payerAddressID  Integer 

Invoice bill-to address ID.

This field only appears if your account has a "Payer" field on invoice form. See the longer explanation above.

 
payerAddress  String 

Invoice bill-to address — full address, formatted.

This field only appears if your account has a "Payer" field on invoice form. See the longer explanation above.

 
payerPaysViaFactoring  Integer 

Indicates this customer pays invoices via factoring. (This is a flag you can set on customer card.)

Possible value: 0 or 1.

This field only appears if your account has a "Payer" field on invoice form. See the longer explanation above.

 
shipToID  Integer 

This field only appears if your account has a "Ship To" field on invoice form. See the longer explanation above.

The recipient of goods ("Ship To") - if different from the payer.

If the recipient and payer are the same person, the "Ship To" field in ERPLY is typically left empty, and fields "shipToID", "shipToAddressId", "shipToAddress" in API output will not contain any values.

 
shipToName  String 

Name of the receiver of goods.

This field only appears if your ERPLY account has a "Ship To" field on invoice form. See the longer explanation above.

 
shipToAddressID  Integer 

The address ID of the receiver of goods.

This field only appears if your ERPLY account has a "Ship To" field on invoice form. See the longer explanation above.

 
shipToAddress  String 

Invoice ship-to address — full address, formatted.

This field only appears if your ERPLY account has a "Ship To" field on invoice form. See the longer explanation above.

 
contactID  Integer    
contactName  String    
employeeID  Integer  Invoice (order, quote) creator ID.  
employeeName  String    
projectID  Integer    
invoiceState  String  PENDING, READY, MAILED, PRINTED, SHIPPED, FULFILLED or CANCELLED  
paymentType  String (10)  Expected invoice payment method: eg. CASH, CARD, TRANSFER, CHECK, GIFTCARD.

This is just an informative field, indicating how the customer will likely pay the invoice. For more accurate information and for reporting, you need to inspect the payments associated with this document. An invoice can have many payments (of different types).

A list of invoice payment methods can be retrieved with getInvoicePaymentTypes. To create your own custom methods (and assign code names if needed), see saveInvoicePaymentType.  
paymentTypeID  Integer  Payment method ID. This provides exactly the same information as field paymentType above — but as an ID, not a code name.  
paymentDays  Integer  In how many days the invoice is due.  
paymentStatus  String  Invoice payment status.
Possible values: PAID, UNPAID.  
baseDocuments  Array  Array of source documents. For an invoice, source documents may be waybills, orders, quotes, or prepayment invoices. For a credit invoice, the source document is the original invoice being credited. This element is always present but may be empty if there are no source documents.

Array elements have the following attributes:
  • id - Integer - Invoice ID
  • number - String - Invoice number
  • type - String - Invoice type (see above for the list of defined types)
  • date - Date (yyyy-mm-dd) - Invoice date.
 
followUpDocuments  Array  This element is always present but may be empty.

Array elements have the following attributes:
  • id - Integer - Invoice ID
  • number - String - Invoice number
  • type - String - Invoice type (see above for the list of defined types)
  • date - Date (yyyy-mm-dd) - Invoice date.
 
previousReturnsExist  Integer  0 or 1  
confirmed  Integer  0 or 1  
notes  String  Notes printed on the invoice  
internalNotes  String  Notes to be displayed on invoice form, as a notice/reminder to other users.  
netTotal  Decimal, 2 places    
vatTotal  Decimal, 2 places    
netTotalsByRate  Array  DEPRECATED — netTotalsByTaxRate is recommended instead.  
vatTotalsByRate  Array  DEPRECATED — vatTotalsByTaxRate is recommended instead.  
netTotalsByTaxRate  Array  List of VAT (tax) rates and invoice net totals for each rate. Each list element contains the following fields:
Field nameTypeDescription
vatrateIDIntegerTax rate ID, see getVatRates
totalDecimalNet total
 
vatTotalsByTaxRate  Array  List of VAT (tax) rates and total VAT (tax) amounts for each rate. Each list element contains the following fields:
Field nameTypeDescription
vatrateIDIntegerTax rate ID, see getVatRates
totalDecimalTotal VAT / tax
 
rounding  Decimal, 2 places    
total  Decimal, 2 places  =netTotal+vatTotal+rounding  
paid  Decimal    
externalNetTotal  Decimal, 4 places  A custom net total for this invoice, possibly calculated by another software. For a description of how this field could be used in practice, see saveSalesDocument, field "externalNetTotal".  
externalVatTotal  Decimal, 4 places  See above.  
externalRounding  Decimal, 4 places  See above.  
externalTotal  Decimal, 4 places  See above.  
taxExemptCertificateNumber  String    
otherCommissionReceivers  Array  Sales associates who receive commission on this sale. If this field is set, commission is divided equally between the people listed in "otherCommissionReceivers".

If the field is not set, commission goes to invoice creator by default, and commission on specific line items may be specially assigned to some other employee — see invoice rows, field "employeeID".  
packerID  Integer    
referenceNumber  String  Sales document's reference number.  
cost  Decimal  Total cost of all items in invoice's currency.

API returns this attribute if parameter "getCOGS" is specified. To get the cost in main currency multiply cost with currencyRate.  
reserveGoods  Integer (0 or 1)  Documents that neither sell the goods nor reserve them in the stock — PREPAYMENT, OFFER and ORDER — can optionally still include a reservation.  
reserveGoodsUntilDate  ISO date (yyyy-mm-dd)  Until what date the reservation is kept.  
deliveryDate  ISO date (yyyy-mm-dd)  Customer requested delivery date (for the whole document).  
deliveryTypeID  Integer    
deliveryTypeName  String    
shippingDate  ISO date (yyyy-mm-dd)  Actual shipping date (for the whole document).  
packingUnitsDescription  String  Description of packing unit.  
triangularTransaction  Integer (0 or 1)    
purchaseOrderDone  Integer (0 or 1)    
transactionTypeID  Integer    
transactionTypeName  String    
transportTypeID  Integer    
transportTypeName  String    
deliveryTerms  String    
deliveryTermsLocation  String    
euInvoiceType  String  Document type. Possible values are "DOMESTIC", "EU", "OUTSIDE_EU".  
deliveryOnlyWhenAllItemsInStock  Integer (0 or 1)    
lastModified  Unix timestamp    
lastModifierUsername  String  Employee's username.  
added  Unix timestamp  Sales invoice creation timestamp.
API returns this attribute if parameter "getAddedTimestamp" is specified.  
invoiceLink  String  URL pointing to a HTML printout version of the document.

This URL is valid only for 24 hours; if you want to send the invoice / order by e-mail, you must retrieve the contents of this URL and enclose it as an attachment, instead of sending the URL itself.  
receiptLink  String  URL pointing to a receipt-sized HTML printout version of the document.

For POS receipts (type = "CASHINVOICE"), both printouts are equivalent, because receipts are always printed in receipt format. The "receiptLink" URL is only necessary for documents that could be printed out either way — eg. orders and laybys.

This URL is valid only for 24 hours; if you want to send the invoice / order by e-mail, you must retrieve the contents of this URL and enclose it as an attachment, instead of sending the URL itself.  
returnedPayments  Array  Array, each item in which has the following attributes:

type - String - payment type
sum - Decimal - payment sum.
API returns this attribute if parameter "getReturnedPayments" is specified.  
amountAddedToStoreCredit  Decimal    
amountPaidWithStoreCredit  Decimal    
applianceID  Integer  Appliance ID. Available only if your account is configured for appliance or vehicle repair.  
applianceReference  String  Appliance reference. Available only if your account is configured for appliance or vehicle repair.  
assignmentID  Integer  Assignment ID. Available only if your account is configured for appliance or vehicle repair.  
vehicleMileage  Integer  Vehicle-specific attribute. Available only if your account is configured for vehicle repair.  
attributes  Array  Additional attributes. Each item looks like this:

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

Field nameTypeDescription
attributeNameStringAttribute name
attributeValueStringAttribute value
 
rows  Array  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. Each invoice row has the following fields:
Field nameTypeDescription
rowIDIntegerInvoice row ID. That is a transient value, it changes every time the document is re-saved. This field has only been provided to provide an easier mapping between getSalesDocuments and getAppliedPromotionRecords.
productIDIntegerProduct ID.

The item on the invoice may be either:
  • a product;
  • a service (although services are deprecated and disabled entirely on newer accounts, so most likely you can ignore that option);
  • or a free-text item (in which case both productID and serviceID are 0 and the only information is item name in the field itemName.
serviceIDIntegerService ID.

Please note that services are deprecated and we recommend to use non-stock products instead.
itemNameStringProduct or service name. This may differ from the product name on product card; users have the option to overwrite name when they add the item to invoice.
codeStringProduct code.
vatrateIDIntegerID of VAT rate.
amountDecimalSold quantity.
priceDecimalNet sales price per item, pre-discount.
discountDecimalDiscount % that WILL BE SUBTRACTED from the price specified in previous parameter.

The algorithm is as follows:

discountedPrice = round((price (100 - discount) / 100), defaultDecimalPlaces)
lineTotal = round(discountedPrice
amount), 2)
lineVat = round((lineTotal * (100 + vatrate) / 100), 2)
finalNetPriceDecimalDiscounted sales price per item, VAT excluded.
finalPriceWithVATDecimalDiscounted sales price per item, VAT included.
rowNetTotalDecimal
rowVATDecimal
rowTotalDecimal
deliveryDateISO date (yyyy-mm-dd)Customer requested delivery date for this specific item.
returnReasonIDIntegerA reason for returning the item (if document is a return), or for discount (if document is a regular sale). Reasons can be listed with API call getReasonCodes.
employeeIDIntegerEmployee receiving commission on the sale of this line item.
campaignIDsStringA comma-separated list of campaigns (sales promotions) that have been applied to this invoice row. Needed for reporting.
containerIDIntegerID of another product, a beverage container that is always sold together with this item.
containerAmountIntegerNumber of beverage containers that this product contains.
originalPriceIsZeroInteger(0 or 1)Indicates that this product has a zero price on product card.
packageIDIntegerPackage ID, if the item has been sold in packages. To retrieve the packages of a particular product, see getProducts, block "productPackages".
amountOfPackagesDecimalAmount of packages
amountInPackageDecimalAmount of products contained in one package
packageTypeStringReadable package type name
packageTypeIDIntegerType ID of the package.
sourceWaybillIDIntegerSource document ID. Only appears on document types CREDITINVOICE and INVOICE. Indicates which waybill this row originated from (if this invoice has been created from one or more waybills).
billingStatementIDIntegerRecurring billing ID, if this invoice line is associated with a recurring billing.

In back office, recurring billings can be found in Sales → Recurring billing and the billings can be retrieved with API call getBillingStatements.
billingStartDateISO date (yyyy-mm-dd)Related to previous field.

Start date of the period for which customer was billed.
billingEndDateISO date (yyyy-mm-dd)Related to previous field.

End date of the period for which the customer was billed.
batchStringAlcohol batch number.

This field is returned only when Alcohol Wholesaling module is enabled.
warehouseValueDoubleProduct unit cost in invoice's currency.
API returns this attribute if parameter getCOGS is specified.

It is the weighted average of each individual item that has been subtracted from inventory using the FIFO principle. To get the cost in main currency multiply cost with currencyRate.