Search

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 nameDescriptionPossible valueRequired
idSearch for a specific sales document by ID.Integer
idsMultiple sales document IDs, separated by commas, such as: 1,2,3,4,5.String
clientIDSearch for invoices by customer ID.Integer
clientIDsMultiple customer IDs, separated by commas, such as: 1,2,3,4,5.String
clientNameString
employeeIDSearch for invoices created by this employee.Integer
warehouseIDSearch for invoices by warehouse ID.Integer
pointOfSaleIDSearch for invoices by point of sale ID.Integer
projectIDSearch for invoices by project ID.Integer
productIDSearch 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
confirmedIf this parameter is supplied, returns either only confirmed, or only non-confirmed sales documents.0 or 1
numberSearch 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
numberOrCustomerSearch 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
dateFromDate (yyyy-mm-dd)
dateToDate (yyyy-mm-dd)
deliveryDateFromSearch by deliveryDate field - customer requested delivery date for whole document.Date (yyyy-mm-dd)
deliveryDateToSearch by deliveryDate field - customer requested delivery date for whole document.Date (yyyy-mm-dd)
rowDeliveryDateFromSearch by deliveryDate field in document rows - customer requested delivery date for one specific item.Date (yyyy-mm-dd)
rowDeliveryDateToSearch by deliveryDate field in document rows - customer requested delivery date for one specific item.Date (yyyy-mm-dd)
typeINVWAYBILL, CASHINVOICE, WAYBILL, PREPAYMENT, OFFER, EXPORTINVOICE, RESERVATION, CREDITINVOICE, ORDER, or INVOICEString
typesYou can specify multiple document types, separated by commas.String
nonReturnedItemsOnlyIf 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
getRowsForAllInvoicesIf 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
getReturnedPaymentsIf set to 1, API also returns returned payments for selected sales documents.
getAddedTimestampIf set to 1, API also returns sales invoice creation timestamp.Unix timestamp.
dueDateFromDate (yyyy-mm-dd)
dueDateToDate (yyyy-mm-dd)
unpaidItemsOnlyIf set to 1, API returns only unpaid sales documents.
getCOGSIf set to 1, API also returns the cost of goods sold.
getUnfulfilledDocumentsIf set to 1, API returns only unfulfilled documents.
invoiceStatePENDING, READY, MAILED, PRINTED, SHIPPED, FULFILLED, CANCELLED or NOT_CANCELLED (returns all documents except cancelled ones)String
assignmentIDInteger
excludeGiftCardsIf 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
changedSinceRetrieve 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)
langRetrieve 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'
orderByDirOrdering direction, 'asc' or 'desc'. By default 'desc'
recordsOnPageNumber of records API should return. By default 20, at most 100.Integer
pageNoAPI 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 nameTypeDescription
idIntegerinvoice ID
typeStringINVWAYBILL, CASHINVOICE, WAYBILL, PREPAYMENT, OFFER, EXPORTINVOICE, RESERVATION, CREDITINVOICE, ORDER or INVOICE
exportInvoiceTypeStringUsed only if document type is EXPORTINVOICE. Value: EU or NOTEU
currencyCodeStringCurrency code: EUR, USD.
currencyRateDecimaleg. 1.25543
Exchange rate of the invoice currency against system's default currency.
warehouseIDIntegerID of the warehouse from which goods are sold.
warehouseNameStringName of the warehouse.
pointOfSaleIDIntegerPoint of sale ID.
pointOfSaleNameStringPoint of sale name.
pricelistIDInteger
numberString
dateDateeg. 2010-01-29
inventoryTransactionDateDateInventory 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.
timeTimeeg. 14:59:00
clientIDInteger

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.

clientNameStringCustomer name.
clientEmailStringCustomer e-mail address.
clientCardNumberStringCode of customer's loyalty/membership card. This corresponds to the "customerCardNumber" field in API call getCustomers.
addressIDIntegerID of customer's address on this invoice.
addressStringCustomer's address — full address, formatted.
clientPaysViaFactoringInteger (0 or 1)Indicates this customer pays invoices via factoring. (This is a flag you can set on customer card.)
payerIDInteger

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.

payerNameString

Invoice payer name.

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

payerAddressIDInteger

Invoice bill-to address ID.

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

payerAddressString

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.

payerPaysViaFactoringInteger

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.

shipToIDInteger

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.

shipToAddressIDInteger

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.

shipToAddressString

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.

contactIDInteger
contactNameString
employeeIDIntegerInvoice (order, quote) creator ID.
employeeNameString
projectIDInteger
invoiceStateStringPENDING, READY, MAILED, PRINTED, SHIPPED, FULFILLED or CANCELLED
paymentTypeString (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.
paymentTypeIDIntegerPayment method ID. This provides exactly the same information as field paymentType above — but as an ID, not a code name.
paymentDaysIntegerIn how many days the invoice is due.
paymentStatusStringInvoice payment status.
Possible values: PAID, UNPAID.
baseDocumentsArrayArray 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.
followUpDocumentsArrayThis 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.
previousReturnsExistInteger0 or 1
confirmedInteger0 or 1
notesStringNotes printed on the invoice
internalNotesStringNotes to be displayed on invoice form, as a notice/reminder to other users.
netTotalDecimal, 2 places
vatTotalDecimal, 2 places
netTotalsByRateArrayDEPRECATED — netTotalsByTaxRate is recommended instead.
vatTotalsByRateArrayDEPRECATED — vatTotalsByTaxRate is recommended instead.
netTotalsByTaxRateArrayList 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
vatTotalsByTaxRateArrayList 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
roundingDecimal, 2 places
totalDecimal, 2 places=netTotal+vatTotal+rounding
paidDecimal
externalNetTotalDecimal, 4 placesA 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".
externalVatTotalDecimal, 4 placesSee above.
externalRoundingDecimal, 4 placesSee above.
externalTotalDecimal, 4 placesSee above.
taxExemptCertificateNumberString
otherCommissionReceiversArraySales 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".
packerIDInteger
referenceNumberStringSales document's reference number.
costDecimalAPI returns this attribute if parameter "getCOGS" is specified.
reserveGoodsInteger (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.
reserveGoodsUntilDateISO date (yyyy-mm-dd)Until what date the reservation is kept.
deliveryDateISO date (yyyy-mm-dd)Customer requested delivery date (for the whole document).
deliveryTypeIDInteger
deliveryTypeNameString
shippingDateISO date (yyyy-mm-dd)Actual shipping date (for the whole document).
packingUnitsDescriptionStringDescription of packing unit.
triangularTransactionInteger (0 or 1)
purchaseOrderDoneInteger (0 or 1)
transactionTypeIDInteger
transactionTypeNameString
transportTypeIDInteger
transportTypeNameString
deliveryTermsString
deliveryTermsLocationString
euInvoiceTypeStringDocument type. Possible values are "DOMESTIC", "EU", "OUTSIDE_EU".
deliveryOnlyWhenAllItemsInStockInteger (0 or 1)
lastModifiedUnix timestamp
lastModifierUsernameStringEmployee's username.
addedUnix timestampSales invoice creation timestamp.
API returns this attribute if parameter "getAddedTimestamp" is specified.
invoiceLinkStringURL 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.
receiptLinkStringURL 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.
returnedPaymentsArrayArray, 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.
amountAddedToStoreCreditDecimal
amountPaidWithStoreCreditDecimal
applianceIDIntegerAppliance ID. Available only if your account is configured for appliance or vehicle repair.
applianceReferenceStringAppliance reference. Available only if your account is configured for appliance or vehicle repair.
assignmentIDIntegerAssignment ID. Available only if your account is configured for appliance or vehicle repair.
vehicleMileageIntegerVehicle-specific attribute. Available only if your account is configured for vehicle repair.
attributesArrayAdditional attributes. Each item looks like this:

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

Field nameTypeDescription
attributeNameStringAttribute name
attributeValueStringAttribute value
rowsArrayIf 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.
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.