getPurchaseDocuments

Returns a list of purchase documents (purchase invoices 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.

If you are looking for a way to pull all purchase data for external processing, see getPurchaseReport. getPurchaseReport 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 ID of a specific purchase document Integer
supplierID Supplier ID. Integer
supplierIDs Multiple supplier IDs, separated by commas, such as: 1,2,3,4,5. String
type PRCINVOICE, CASHPRCINVOICE, PRCORDER, PRCRETURN, PRCWAYBILL or PRCINVOICEONLY. See explanation below! String
status PENDING, PARTIALLY_RECEIVED, RECEIVED or READY. See explanation below! String
stateID Purchase document status ID Integer
dateFrom Filter by purchase document date field Date (yyyy-mm-dd)
dateTo Filter by purchase document date field Date (yyyy-mm-dd)
confirmed 0 or 1 Integer
paid 0 or 1 Integer
number Number of purchase document. String
referenceNumber Reference number of purchase document. String
warehouseID Warehouse ID. Integer
regnumber Reg. number of purchase document. String
employeeID ID of the system employee, who is set as the creator of the invoice/order/etc. Integer
shipDateFrom Filter by the ship date field Date (yyyy-mm-dd)
shipDateTo Filter by the ship date field Date (yyyy-mm-dd)
getRowsForAllInvoices Set this field to 1 to retrieve the rows for each returned purchase document.

Not that in some cases, rows are returned anyway — see the specification of the "rows" field below.
0 or 1
getCost Set this field to 1 to retrieve the inventory cost of each purchased item.

Cost is only a property of purchase invoices (not POs), and only products have a cost (services do not, since services are not taken into inventory). Cost is the sum of purchase price, plus shipping and other costs divided between invoice items.

If set to 1, API will return "unitCost" and "costTotal" for each document row, and "cost" for the whole document.
0 or 1
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
orderBy 'documentID', 'dateAndNumber', 'supplierName', or 'lastChanged'. By default 'dateAndNumber' String
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
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)

Response

Field name Type Description
id Integer Purchase document ID
type String If your account has configuration setting use_purchase_waybills enabled, then the possible types are:
PRCORDERPurchase order
PRCINVOICEPurchase invoice-waybill. Takes items into stock and affects your Accounts Payable.

A Purchase Invoice-Waybill is equivalent to making a Purchase Waybill (PRCWAYBILL), followed by a Purchase Invoice (PRCINVOICEONLY)
CASHPRCINVOICEPurchase receipt. Same as previous.
PRCRETURNPurchase return. Functionally same as a purchase invoice-waybill, but it is used to return goods back to supplier.

On a purchase return, amounts are negative.
PRCWAYBILLPurchase waybill. This document ONLY takes items into stock, and does not generate an obligation to pay.
PRCINVOICEONLYPurchase invoice. This is usually a follow-up for the items that have arrived earlier with an invoice-waybill.

For example, the supplier may send shipments continuously throughout the month, and bill the customer once a month, for all the shipments sent.

The invoice does not affect stock, but it affects your Accounts Payable.


If the setting is not enabled, possible types are:
PRCORDERPurchase order
PRCINVOICEPurchase invoice-waybill. Takes items into stock and affects your Accounts Payable. (Here, we can also call it a "purchase invoice" for short, since there are no other similar document types.)
CASHPRCINVOICEPurchase receipt. Same as previous.
PRCRETURNPurchase return. Functionally same as a purchase invoice-waybill, but it is used to return goods back to supplier.
status String The possible statuses are:
PENDINGDocument not confirmed.
PARTIALLY_RECEIVEDPurchase order (PRCORDER) only. Document has been confirmed and its status is "partially received". This status can be set manually, but typically this means that the PO has been associated with a purchase invoice, or purchase invoices, but not all ordered items have been received yet.
RECEIVEDPurchase order (PRCORDER) only. Document is confirmed and its status is "received".
READYAny other confirmed purchase document (for example a purchase invoice or a purchase return) — or a confirmed purchase order that has not been fulfilled yet.
currencyCode String Currency code: EUR, USD.
currencyRate Decimal eg. 1.25543
Exchange rate of the purchase document currency against system's default currency.
warehouseID Integer ID of the warehouse
warehouseName String Name of the warehouse
number String Number of purchase document
regnumber String Reg. number of purchase document
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
supplierID Integer
supplierName String
supplierGroupID Integer ID of supplier's group (see getSupplierGroups).
addressID Integer
address String
contactID Integer
contactName String
employeeID Integer ID of the system employee, who is set as the creator of the invoice/order/etc.
employeeName String
supplierID2 Integer
supplierName2 String
stateID Integer
paymentDays Integer In how many days the purchase document is due.
paid Integer 0 or 1
transactionTypeID Integer
transportTypeID Integer
deliveryTermsID Integer
deliveryTermsLocation String
triangularTransaction Integer 0 or 1
projectID Integer
confirmed Integer 0 or 1
referenceNumber String
notes String
rounding Decimal, 2 places
netTotal Decimal
vatTotal Decimal
total Decimal =netTotal+vatTotal+rounding
netTotalsByTaxRate Array List of VAT (tax) rates and purchase document 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
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 purchase invoice / PO by e-mail, you must retrieve the contents of this URL and enclose it as an attachment, instead of sending the URL itself.
shipDate Date eg. 2010-01-29
cost Decimal Total inventory cost of the purchased products. Cost equals invoice net total, less services and non-stock products (since services are not taken into inventory, they can never have cost) + shipping and handling costs.

Cost is always in account's default currency. This field is returned only if you set getCost = 1.
netTotalForAccounting Decimal, 2 places
totalForAccounting Decimal, 2 places
baseToDocuments Array Array of purchase documents that have been made from this document. This element is always present but may be empty if there are no documents.

Array elements have the following attributes:
  • id - Integer - Purchase Document ID
  • number - String - Number of purchase document
  • regnumber - String - Reg. number of purchase document
  • type - String - Type of purchase document
  • date - Date (yyyy-mm-dd) - Date of purchase document
baseDocuments Array Array of source documents. This element is always present but may be empty if there are no source documents.

Array elements have the following attributes:
  • id - Integer - Purchase Document ID
  • number - String - Number of purchase document
  • regnumber - String - Reg. number of purchase document
  • type - String - Type of purchase document
  • date - Date (yyyy-mm-dd) - Date of purchase document
lastModified Unix timestamp
rows Array Purchase document rows. Rows are returned only in specific cases (if you searched purchase document by ID or number, or if result set contained just one document, or if you specified getRowsForAllInvoices = 1. Each row (ie. each array element) has the following fields:
Field nameTypeDescription
productIDInteger
serviceIDInteger
itemNameString
codeString
code2String
vatrateIDIntegerID of VAT rate.
amountDecimal
priceDecimalNet price per item
discountDecimal
deliveryDateDateSupplier quoted delivery date. Available only if the feature "Delivery date tracking on sales and purchase orders" is enabled on your account.
unitCostDecimalInventory cost for 1 unit. Cost is always in account's default currency. Returned only if you set getCost = 1.
costTotalDecimalunitCost multiplied by amount. Returned only if you set getCost = 1.
packageIDIntegerPackage ID, if the item has been purchased 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.
attributes Array Additional attributes for the document. Each array element has the following fields:
Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringValue of the attribute