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.  
   
searchAttributeName  Search from attribute name.searchAttributeName and searchAttributeValue have to be specified both  String    
searchAttributeValue  Search from attribute value  String    
orderBy    'dateAndNumber', 'supplierName', 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    
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  
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