REST API Entity - Purchases

This s a documentation page for our shiny new REST API - you weren't meant to find it. This API isn't ready for public use yet. We're chopping and changing it a LOT as we grow it. So if you build something that uses it then it's very likely to break in a future update. Don't say you weren't warned!

URL:	https://api.kashflow.com/v2/purchases
Method(s):	get,post, put,delete
Response Formats:	JSON, XML
Description:	These methods allow you to retrieve/create/update/delete purchases. The individual resource is identified by the purchase number. So /purchases/10 would return the purchase with number 10. A GET to /purchases will return a paginated list of purchases. {number} in the URL would be replaced with the unique number given to purchase.

Parameters

Name	Type	Description
Number	Numeric	Unique purchase identifier. While creating purchase, if a value is passed for this field, then the purchase is created with this number (if it is unique w.r.t the user)
IssuedDate	Date	Date the purchase was issued For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
DueDate	Date	Date the purchase should be paid by For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
PaidDate	Date	Purchase payment date For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
VATAmount	Numeric	Total VAT amount
NetAmount	Numeric	Amount excluding VAT
TotalPaidAmount	Numeric	Total amount paid in home currency
Status	String	Indicates payment status of the purchase. Payment status can be Unpaid, Paid, Overpaid, Overdue or NA . NA indicates purchase amount is zero.
GrossAmount	Numeric	Gross amount
HomeCurrencyGrossAmount	Numeric	Home currency gross amount
Currency	Object	Currency related information such as Code, Name, Exchange Rate
LineItems	Collection	Collection of line items
PaymentLines	Collection	Collection of all payments made
SupplierId	Numeric	Unique database id assigned to supplier
SupplierCode	String	Code of the supplier the purchase is created for
SupplierReference	String	Supplier reference
SupplierName	String	Supplier name
OverdueDays	Numeric	Number of days the purchase payment is overdue by
ProjectNumber	Numeric	Project number assigned to purchase
Permalink	String	Permanent url of purchase document that can be shared.
AdditionalFieldValue	String	Value of the additional field, if set for the user
PreviousNumber	Numeric	Previous purchase number
NextNumber	Numeric	Next purchase number
PurchaseInECMemberState	Boolean	Flag indicating whether supplier is VAT registered in EC member state or not.
IsWhtDeductionToBeApplied	Boolean	Whether this purchase is eligible for withholding tax deduction.
StockManagementApplicable	Boolean	Flag indicating whether stock management is applicable for purchase. This is read-only field and only returned in case of single GET.
FileCount	Numeric	Count of files
Line items collection parameters
Number	Numeric	This field serves 2 purposes: 1. It uniquely identifies a line item. 2. It represents the sort order, i.e., items can be displayed in the line items list in the same order (Ascending) as their line number. Note : Though line number uniquely identifies a line, but it may change when sort order is altered. Also, it should be set to 0 for new line item.
Description	String	Description for this line item
Quantity	Numeric	Units of line item
Rate	Numeric	The rate in quote currency
HomeCurrencyRate	Numeric	Rate of the line item in home currency.
VATLevel	Numeric	VAT rate applied to the purchase line. This field is read only.
VATExempt	Numeric	Vat Exemption value
VATAmount	Numeric	VAT amount of the purchase
HomeCurrencyVATAmount	Numeric	VAT amount of the purchase line in home currency.
NominalCode	String	Nominal code the purchase line is assigned to
ProductCode	Numeric	Unique code of the product
ProductName	String	Name of the product
ProjectNumber	Numeric	Number of the project assigned to purchase line
ProjectName	String	Name of the project assigned to purchase line.
NominalName	String	Name of the nominal assigned to purchase line.
Payment lines collection parameters
Id	Numeric	Unique Id of the payment line created
AccountId	Numeric	The bank account id the payment is assigned to
Date	Date	Date of this transaction. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
Note	String	Description of this transaction
Method	Numeric	Payment method Id
Amount	Numeric	Amount that was paid
Permalink	String	Permanent URL of purchase payment document that can be shared.
BulkId	Numeric	Bulk payment id
BulkPaymentNumber	Numeric	Bulk payment number
Permalink	Numeric	Permanent link to print purchase payment
BankTransactionId	Numeric	Bank Transaction Id

GET Operation

Returns a paginated list of purchases. To GET list of purchases –

URL : /purchases?page={page}&perpage={perpage}&sortby={sortby}&order={order}&filterby={filterby}&projectnumber={projectnumber}&suppliercode={suppliercode}

A paginated list of purchases is returned (ordered by purchase number in ascending order).

Example response for GET of purchase list


{
    "Data": [{
        "Currency": {
            "Code": "GBP",
            "DisplaySymbolOnRight": false,
            "ExchangeRate": 1.0000,
            "Name": "British Pounds",
            "Symbol": "£"
        },
        "DueDate": "2008-12-27 12:00:00",
        "GrossAmount": 14.9800,
        "Id": 600504,
        "IssuedDate": "2008-11-27 12:00:00",
        "LineItems": null,
        "NetAmount": 17.2300,
        "Number": 3,
        "OverdueDays": 0,
        "PaidDate": "2007-11-27 12:00:00",
        "PaymentLines": null,
        "Permalink": null,
        "Status": "Overpaid",
        "SupplierCode": "FOOD01",
        "SupplierId": 104897,
        "SupplierName": "Food Essentials",
        "SupplierReference": "FOOD001",
        "TotalPaidAmount": 17.2300,
        "VATAmount": 2.2500,
        "FileCount": 2 
    }, {
        "Currency": {
            "Code": "GBP",
            "DisplaySymbolOnRight": false,
            "ExchangeRate": 1.0000,
            "Name": "British Pounds",
            "Symbol": "£"
        },
        "DueDate": "2008-12-27 12:00:00",
        "GrossAmount": 114.9800,
        "Id": 600534,
        "IssuedDate": "2008-11-27 12:00:00",
        "LineItems": null,
        "NetAmount": 114.9800,
        "Number": 4,
        "OverdueDays": 0,
        "PaidDate": null,
        "PaymentLines": null,
        "Permalink": null,
        "Status": "Overdue",
        "SupplierCode": "FOOD01",
        "SupplierId": 104897,
        "SupplierName": "Food Essentials",
        "SupplierReference": "FOOD001",
        "TotalPaidAmount": 14.9800,
        "VATAmount": 0.0000,
        "FileCount": 0
    }, {
        "Currency": {
            "Code": "GBP",
            "DisplaySymbolOnRight": false,
            "ExchangeRate": 0.0000,
            "Name": "British Pounds",
            "Symbol": "£"
        },
        "DueDate": "2008-12-27 12:00:00",
        "GrossAmount": 14.9800,
        "Id": 675537,
        "IssuedDate": "2008-11-27 12:00:00",
        "LineItems": null,
        "NetAmount": 14.9800,
        "Number": 5,
        "OverdueDays": 0,
        "PaidDate": null,
        "PaymentLines": null,
        "Permalink": null,
        "Status": "Overdue",
        "SupplierCode": "FOOD01",
        "SupplierId": 104897,
        "SupplierName": "Food Essentials",
        "SupplierReference": "FOOD001",
        "TotalPaidAmount": 44.9800,
        "VATAmount": 0.0000,
        "FileCount": 1
    }],
    "MetaData": {
        "FirstPageUrl": "https:\/\/api.kashflow.com\/v2\/purchases?page=1&perpage=3&sortby=Number&order=Asc",
        "LastPageUrl": "https:\/\/api.kashflow.com\/v2\/purchases?page=109&perpage=3&sortby=Number&order=Asc",
        "NextPageUrl": "https:\/\/api.kashflow.com\/v2\/purchases?page=2&perpage=3&sortby=Number&order=Asc",
        "PreviousPageUrl": null,
        "TotalRecords": 325
    }
}

Request Parameters

Name	Description
page	The page number
perpage	Number of records to be fetched
sortby	Index of the column on which sorting needs to be applied. The acceptable values for this parameter are: 1. Number 2. Supplierreference 3. SupplierName 4. PurchaseDate 5. PaymentDueDate 6. GrossAmount 7. NetAmount 8. Status 9. PaidDate
order	Sort direction can be either Asc for ascending or Desc for descending.
filterby	The list can be filtered by purchase status. Set this parameter to “All” or empty or exclude from the URL if all purchases are to be retrieved. The acceptable values for this parameter are: 1. All 2. Unpaid 3. Overdue 4. Overpaid 5. Paid 6. ThisMonth 7. LastMonth
projectnumber	Retrieve purchases for a particular project. Set to 0 or empty or exclude from URL to exclude this filter
suppliercode	Retrieve purchase for a particular supplier. You don’t need to specify it if you don’t want the invoice list to be filtered by supplier code

To get a particular purchase with all details –
URL : /purchases /{number}

Example response for GET of purchase


{
    "AdditionalFieldValue": "123",
    "Currency": {
        "Code": "AUD",
        "DisplaySymbolOnRight": false,
        "ExchangeRate": 2.0000,
        "Name": "Australian Dollars",
        "Symbol": "$"
    },
    "DueDate": "2014-01-10 12:00:00",
    "GrossAmount": 195.080000,
    "HomeCurrencyGrossAmount": 97.5400,
    "Id": 17356452,
    "IsWhtDeductionToBeApplied": true,
    "IssuedDate": "2014-01-10 12:00:00",
    "FileCount": 2,
    "LineItems": [{
        "Description": "product description",
        "HomeCurrencyRate": 7.50,
        "HomeCurrencyVATAmount": 3.04,
        "NominalCode": 5000,
        "Number": 1,
        "ProductCode": "Test121",
        "ProductName": "Material",
        "Quantity": 3.0000,
        "Rate": 15.00,
        "TaxCode": null,
        "VATAmount": 6.08,
        "VATExempt": false,
        "VATLevel": 13.5000,
        "NominalName": "Materials Purchased",
        "ProjectName": "Test5",
        "ProjectNumber": 2,
        "StockInfo": {
            "QuantityInStock": 22,
            "Received": false,
            "StockReceivedOn": null,
            "Type": "Product"
        }
    }, {
        "Description": "line item 2",
        "HomeCurrencyRate": 6.00,
        "HomeCurrencyVATAmount": 12.00,
        "NominalCode": 7403,
        "Number": 2,
        "ProductCode": "",
        "ProductName": "",
        "Quantity": 10.0000,
        "Rate": 12.00,
        "TaxCode": null,
        "VATAmount": 24.00,
        "VATExempt": false,
        "VATLevel": 20.0000,
        "NominalName": "Entertainment",
        "ProjectName": "TEst",
        "ProjectNumber": 1,
        "StockInfo": null
    }],
    "NetAmount": 165.000000,
    "NextNumber": 0,
    "Number": 2344375,
    "OverdueDays": 0,
    "PaidDate": null,
    "PaymentLines": [],
    "Permalink": "\/v2\/documents\/purchaseorder\/3e196af3-7c11-46f1-b145-e3c8212b4d30",
    "PreviousNumber": 2344374,
    "PurchaseInECMemberState": false,
    "Status": "Unpaid",
    "StockManagementApplicable": false,
    "SupplierCode": "08C",
    "SupplierId": 433398,
    "SupplierName": "Honda Suppliers",
    "SupplierReference": "wieu231",
    "TotalPaidAmount": 0.0000,
    "VATAmount": 30.08
}

POST Operation

Creates a new purchase record with the given purchase data using following URL –

URL : /purchases/

Example request for POST of a purchase

Purchase can be created just with its header details (i.e. with out line items and payment lines) or just with line items in unpaid state. You need to leave tag blank, with no sub-tag. Purchase can be created with multiple purchase line items and same as with payment lines.


{
    "Currency": {
        "Code": "GBP",
        "DisplaySymbolOnRight": false,
        "ExchangeRate": 1,
        "Name": "British Pounds",
        "Symbol": "£"
    },
    "DueDate": "2013-12-27 12:00:00",
    "IssuedDate": "2013-11-27 12:00:00",
    "LineItems": [{
        "Description": "Purchase line description",
        "HomeCurrencyRate": 10.99,
        "HomeCurrencyVATAmount": 0.00,
        "NominalCode": 8205,
        "ProductCode": "",
        "ProductName": "",
        "Quantity": 1.0000,
        "Rate": 10.99,
        "TaxCode": null,
        "VATAmount": 0.00,
        "VATExempt": false,
        "VATLevel": 0.0000,
        "NominalName": "BT Bill",
        "ProjectName": "KashFlow API",
        "ProjectNumber": 1
    }],
    "PaymentLines": [{
        "AccountId": 16437,
        "Amount": 10.99,
        "Date": "2013-11-27 12:00:00",
        "Method": 56752,
        "Note": "Card Payment"
    }]
    "AdditionalFieldValue": "PRM08989",
    "SupplierCode": "FOOD01",
    "SupplierReference": "FOOD001"
}

URL : /purchaselist/

Example request for bulk POST of purchases

Multiple purchases can be created using this api. All the details of each purchases can be specified in same way as when using single post of purchase.
When specifying “BankTransactionId” in payment item, the corresponding transaction will be converted to payment item and a corresponding line item will be created for newly created purchase. Also the following bank transaction will be deleted after this.
Only one “BankTransactionId” can be specified among multiple payment items in each purchase. API returns HTTP 200 status in return even in case of failure/bad request. Status of each purchase can be seen individually with the details. If “BankTransactionId” is not specified then API will work in same way as a single post of purchase.


[
 {
   "SupplierCode": "XYZ01",
   "IssuedDate": "2014-09-29",
   "DueDate": "2014-09-30"
 },
 {
   "SupplierCode": "XYZ01",
   "IssuedDate": "2014-09-30",
   "DueDate": "2014-09-30",
   "PaymentLines": [{"BankTransactionId": 31413499, "Method": 48}]
 }
]

`PUT Operation`

 Updates an existing purchase record with the given purchase data using following URL -
URL : /purchases/{number}
Example request for PUT of a purchase
To update a purchase you need to provide the full purchase data, same as the GET response of that purchase. You then update the required data field(s) or if you want to a add line item or payment line to an existing purchase.
To create a new line item or payment, the item or payment number should be set to 0.
If existing line item(s) is/are not passed in PUT request body, then those line item(s) are deleted.

{
    "AdditionalFieldValue": "123",
    "Currency": {
        "Code": "AUD",
        "DisplaySymbolOnRight": false,
        "ExchangeRate": 2.0000,
        "Name": "Australian Dollars",
        "Symbol": "$"
    },
    "DueDate": "2014-01-10 12:00:00",
    "GrossAmount": 195.080000,
    "HomeCurrencyGrossAmount": 97.5400,
    "Id": 17356452,
    "IsWhtDeductionToBeApplied": true,
    "IssuedDate": "2014-01-10 12:00:00",
    "LineItems": [{
        "Description": "product description",
        "HomeCurrencyRate": 7.50,
        "HomeCurrencyVATAmount": 3.04,
        "NominalCode": 5000,
        "Number": 1,
        "ProductCode": "Test121",
        "ProductName": "Material",
        "Quantity": 3.0000,
        "Rate": 15.00,
        "TaxCode": null,
        "VATAmount": 6.08,
        "VATExempt": false,
        "VATLevel": 13.5000,
        "NominalName": "Materials Purchased",
        "ProjectName": "Test5",
        "ProjectNumber": 2,
        "StockInfo": {
            "QuantityInStock": 22,
            "Received": true,
            "StockReceivedOn": null,
            "Type": "Product"
        }
    }, {
        "Description": "line item 2",
        "HomeCurrencyRate": 6.00,
        "HomeCurrencyVATAmount": 12.00,
        "NominalCode": 7403,
        "Number": 2,
        "ProductCode": "",
        "ProductName": "",
        "Quantity": 10.0000,
        "Rate": 12.00,
        "TaxCode": null,
        "VATAmount": 24.00,
        "VATExempt": false,
        "VATLevel": 20.0000,
        "NominalName": "Entertainment",
        "ProjectName": "TEst",
        "ProjectNumber": 1,
        "StockInfo": null
    }],
    "NetAmount": 165.000000,
    "NextNumber": 0,
    "Number": 2344375,
    "OverdueDays": 0,
    "PaidDate": null,
    "PaymentLines": [],
    "Permalink": "\/v2\/documents\/purchaseorder\/3e196af3-7c11-46f1-b145-e3c8212b4d30",
    "PreviousNumber": 2344374,
    "PurchaseInECMemberState": false,
    "Status": "Unpaid",
    "StockManagementApplicable": false,
    "SupplierCode": "08C",
    "SupplierId": 433398,
    "SupplierName": "Honda Suppliers",
    "SupplierReference": "wieu231",
    "TotalPaidAmount": 0.0000,
    "VATAmount": 30.08
}

DELETE Operation
 Deletes the purchase with the number provided in the URL.
URL : /purchases/{number} 
Stock Management
Stock management is supported in Purchases API. Each line item contains a "StockInfo" object which gives information related to stock.

"StockInfo": {
  "ApplicableOn": "Product",
  "Name": "Test",
  "QuantityInStock": 60,
  "Received": true,
  "StockReceivedOn": "2013-12-12 12:00:00"
}

Name Type Description
QuantityInStock Numeric Quantity available in stock
Received Boolean Stock is received or not. If this is set to True in PUT API stocks will be marked as received. Received status will be returned in GET API.
StockReceivedOn Date This is read-only field. It indicates date on which stock is received For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
Name String Nominal or product name on which stock changes will be applied.
ApplicableOn String Indicates whether stock management is applicable on nominal or product. Possible values are 'Nominal' or 'Product'

Purchases

URL:

Method(s):

Response Formats:

Description:

Parameters

GET Operation

Example response for GET of purchase list

Request Parameters

Example response for GET of purchase

POST Operation

Example request for POST of a purchase

Example request for bulk POST of purchases

`PUT Operation`

Example request for PUT of a purchase

DELETE Operation

In This Section

REST API Methods

Supplementary Functions

Bank

Customers

Purchases

Invoices

Name	Type	Description
QuantityInStock	Numeric	Quantity available in stock
Received	Boolean	Stock is received or not. If this is set to True in PUT API stocks will be marked as received. Received status will be returned in GET API.
StockReceivedOn	Date	This is read-only field. It indicates date on which stock is received For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
Name	String	Nominal or product name on which stock changes will be applied.
ApplicableOn	String	Indicates whether stock management is applicable on nominal or product. Possible values are 'Nominal' or 'Product'