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. When configuration parameter "api_getsalesdocuments_default_customer_sales_not_returned" is applied, and you use getSalesDocuments call with input parameter "clientID", and this is the ID of a default client, API returns an empty response. 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
webShopOrderNumber Search by Web Shop Order Number. String
trackingNumber Search by tracking number String (255)
fulfillmentStatus Search by fulfillment status String (255)
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)
deliveryTypeID Delivery type ID. Integer
transactionTypeID Integer
transportTypeID Integer
deliveryTermsID Integer
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.

By default, the comparison is done by product. Erply does not track which original invoice row is associated with which credit invoice row.

However, more detailed tracking is supported, too, if needed. If your application creates credit invoices and knows exactly which line was credited, use the JSON API to attach the following JSON to credit document's rows:
{"CreditInvoice": {"creditedStableRowID": 1234}}
where 1234 is the "stable row ID" of the original row.

If this information is present in the output, API will use it. If this extra information is missing, API will fall back to usual behavior.
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. 0 or 1
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. 0 or 1
paidItemsOnly If set to 1, API returns only paid sales documents. 0 or 1
getCOGS If set to 1, API also returns the cost of goods sold. 0 or 1
getUnfulfilledDocuments If set to 1, API returns only unfulfilled documents. 0 or 1
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
getCreditInvoicesByOriginalInvoiceID Search for credit invoices that have been made from the specified original invoice. Integer
getReservationsByAssignmentID Search for reservations by assignment ID. Integer
searchAttributeName Name of attribute to search from. Both "searchAttributeName" and "searchAttributeValue" have to be specified. Error 1030 will be returned if value is an array. String
searchAttributeValue Attribute value to search for. Error 1030 will be returned if value is an array. String
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 'documentID', 'dateAndNumber', 'clientName', or 'lastChanged'. By default 'documentID'
orderByDir Sort direction: 'asc' (ascending order) or 'desc' (descending order). By default, items are sorted in descending order. String
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
getFields Comma separated list of fields. Can be used to limit the top level fields that are returned (nested fields are not filtered). When omitted then everything will be returned.

NOTE: When using this filter with a result that does not have the set field then an empty result will be returned.
String
getTaxComponents If this parameter is specified, response will always include tax amount breakdown per component to data. Available only if "City, county and state tax rates" module is enabled on your account. 0 or 1

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.
clientFactoringContractNumber String (255) Factoring contract number.
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", "payerFactoringContractNumber", "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.

payerFactoringContractNumber String (255) Factoring contract number.
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
shipToContactID Integer/Null

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

The contact person of the recipient of goods.

shipToContactName String

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

Name of the contact person of the recipient of goods.

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
printDiscounts Integer Whether the discount % for discounted items should be printed on the invoice, 0 or 1
algorithmVersion Integer (nullable) Algorithm version that has been manually set for the document. Returns NULL if its not set.
algorithmVersionCalculated Integer The final algorithm version that is actually used by the document.
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 Invoice net total.
vatTotal Decimal, 2 places

Invoice total tax (total VAT).

Please note that any possible effect from payments is ignored. If the customer has paid with a "single-purpose voucher" (as defined in EU Council Directive 2016/1065), which essentially is a gift card with VAT, then API getSalesDocuments does not show the sales document's vatTotal as being correspondingly smaller.

If you need the true amount of VAT for accounting purposes, you need to inspect the related payments yourself.

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
componentsArrayAvailable only if "City, county and state tax rates" module is enabled on your account. Array elements have the following attributes:
  • name - String - Tax component name
  • rate - Double - Tax component rate
  • type - String - Tax component type
  • amountOfTax - Double - Tax component tax amount.
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. If a sales document has a custom reference number, API returns this number (otherwise returns a standard generated number).
webShopOrderNumbers Array Web Shop Order Numbers.
trackingNumber String Document tracking number.
fulfillmentStatus String Fulfillment status as some agreed string value.
customReferenceNumber String Sales document's custom 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.
penalty String Penalty for late payments as % per day, eg. "0,5"
This field is only informative and system does not account penalty automatically, can be populated manually.
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", "EU_WITH_VAT", "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.

Alternatively, instead of the standard printout, you can retrieve a custom printout with API call getSalesDocumentActualReportsHTML, using an Actual Reports template of your choice.

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.
ids - array - Id's of the payments.
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.
customNumber String
advancePayment Decimal
advancePaymentPercent Integer
printWithOriginalProductNames Integer (0 or 1)
hidePrices Integer (0 or 1)
hideAmounts Integer (0 or 1)
hideTotal Integer (0 or 1)
isFactoringInvoice Integer (0 or 1)
taxOfficeID Integer
periodStartDate ISO date (yyyy-mm-dd)
periodEndDate ISO date (yyyy-mm-dd)
orderArrived Integer (0 or 1)
orderInvoiced Integer (0 or 1)
hidePaymentDays Integer (0 or 1)
creditInvoiceType String Credit invoice type either VOID or RETURN.
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.
stableRowIDIntegerStable row ID. ID that will be persisted for the row if the row is the same between saves.
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.
jdocObjectContains data that is saved using the JSON Api. Contents of this field change depending on what is saved into the json field. Output is always given as valid json or null when the field is not set.
Example: {"myValue":"123"}