Search

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 nameDescriptionPossible valueRequired
idID of a specific purchase documentInteger
supplierIDSupplier ID.Integer
supplierIDsMultiple supplier IDs, separated by commas, such as: 1,2,3,4,5.String
typePRCINVOICE, CASHPRCINVOICE, PRCORDER, PRCRETURN, PRCWAYBILL or PRCINVOICEONLY. See explanation below!String
statusPENDING, PARTIALLY_RECEIVED, RECEIVED or READY. See explanation below!String
stateIDPurchase document status IDInteger
dateFromFilter by purchase document date fieldDate (yyyy-mm-dd)
dateToFilter by purchase document date fieldDate (yyyy-mm-dd)
confirmed0 or 1Integer
paid0 or 1Integer
numberNumber of purchase document.String
warehouseIDWarehouse ID.Integer
regnumberReg. number of purchase document.String
employeeIDID of the system employee, who is set as the creator of the invoice/order/etc.Integer
shipDateFromFilter by the ship date fieldDate (yyyy-mm-dd)
shipDateToFilter by the ship date fieldDate (yyyy-mm-dd)
getRowsForAllInvoicesSet 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
getCostSet 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.
searchAttributeNameSearch from attribute name.searchAttributeName and searchAttributeValue have to be specified bothString
searchAttributeValueSearch from attribute valueString
orderBy'dateAndNumber', 'supplierName', 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
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)

Response

Field nameTypeDescription
idIntegerPurchase document ID
typeStringIf 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.
statusStringThe 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.
currencyCodeStringCurrency code: EUR, USD.
currencyRateDecimaleg. 1.25543
Exchange rate of the purchase document currency against system's default currency.
warehouseIDIntegerID of the warehouse
warehouseNameStringName of the warehouse
numberStringNumber of purchase document
regnumberStringReg. number of purchase document
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
supplierIDInteger
supplierNameString
supplierGroupIDIntegerID of supplier's group (see getSupplierGroups).
addressIDInteger
addressString
contactIDInteger
contactNameString
employeeIDIntegerID of the system employee, who is set as the creator of the invoice/order/etc.
employeeNameString
supplierID2Integer
supplierName2String
stateIDInteger
paymentDaysIntegerIn how many days the purchase document is due.
paidInteger0 or 1
confirmedInteger0 or 1
referenceNumberString
notesString
roundingDecimal, 2 places
netTotalDecimal
vatTotalDecimal
totalDecimal=netTotal+vatTotal+rounding
netTotalsByTaxRateArrayList 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
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
invoiceLinkStringURL 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.
shipDateDateeg. 2010-01-29
costDecimalTotal 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.
netTotalForAccountingDecimal, 2 places
totalForAccountingDecimal, 2 places
baseToDocumentsArrayArray 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
baseDocumentsArrayArray 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
lastModifiedUnix timestamp
rowsArrayPurchase 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.
attributesArrayAdditional attributes for the document. Each array element has the following fields:
Field nameTypeDescription
attributeNameStringAttribute name
attributeTypeStringAttribute type
attributeValueStringValue of the attribute