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

NameTypeDescription
NumberNumericUnique 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)
IssuedDateDateDate the purchase was issued For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
DueDateDateDate the purchase should be paid by For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
PaidDateDatePurchase payment date For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
VATAmountNumericTotal VAT amount
NetAmountNumericAmount excluding VAT
TotalPaidAmountNumericTotal amount paid in home currency
StatusStringIndicates payment status of the purchase. Payment status can be Unpaid, Paid, Overpaid, Overdue or NA . NA indicates purchase amount is zero.
GrossAmountNumericGross amount
HomeCurrencyGrossAmountNumericHome currency gross amount
CurrencyObjectCurrency related information such as Code, Name, Exchange Rate
LineItemsCollectionCollection of line items
PaymentLinesCollectionCollection of all payments made
SupplierIdNumericUnique database id assigned to supplier
SupplierCodeStringCode of the supplier the purchase is created for
SupplierReferenceStringSupplier reference
SupplierNameStringSupplier name
OverdueDaysNumericNumber of days the purchase payment is overdue by
ProjectNumberNumericProject number assigned to purchase
PermalinkStringPermanent url of purchase document that can be shared.
AdditionalFieldValueStringValue of the additional field, if set for the user
PreviousNumberNumericPrevious purchase number
NextNumberNumericNext purchase number
PurchaseInECMemberStateBooleanFlag indicating whether supplier is VAT registered in EC member state or not.
IsWhtDeductionToBeAppliedBooleanWhether this purchase is eligible for withholding tax deduction.
StockManagementApplicableBooleanFlag indicating whether stock management is applicable for purchase. This is read-only field and only returned in case of single GET.
FileCountNumericCount of files
Line items collection parameters
NumberNumericThis 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.
DescriptionStringDescription for this line item
QuantityNumericUnits of line item
RateNumericThe rate in quote currency
HomeCurrencyRateNumericRate of the line item in home currency.
VATLevelNumericVAT rate applied to the purchase line. This field is read only.
VATExemptNumericVat Exemption value
VATAmountNumericVAT amount of the purchase
HomeCurrencyVATAmountNumericVAT amount of the purchase line in home currency.
NominalCodeStringNominal code the purchase line is assigned to
ProductCodeNumericUnique code of the product
ProductNameStringName of the product
ProjectNumberNumericNumber of the project assigned to purchase line
ProjectNameStringName of the project assigned to purchase line.
NominalNameStringName of the nominal assigned to purchase line.
Payment lines collection parameters
IdNumericUnique Id of the payment line created
AccountIdNumericThe bank account id the payment is assigned to
DateDateDate of this transaction. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
NoteStringDescription of this transaction
MethodNumericPayment method Id
AmountNumericAmount that was paid
PermalinkStringPermanent URL of purchase payment document that can be shared.
BulkIdNumericBulk payment id
BulkPaymentNumberNumericBulk payment number
PermalinkNumericPermanent link to print purchase payment
BankTransactionIdNumericBank 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

NameDescription
pageThe page number
perpageNumber of records to be fetched
sortbyIndex 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
orderSort direction can be either Asc for ascending or Desc for descending.
filterbyThe 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
projectnumberRetrieve purchases for a particular project. Set to 0 or empty or exclude from URL to exclude this filter
suppliercodeRetrieve 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"
}

NameTypeDescription
QuantityInStockNumericQuantity available in stock
ReceivedBooleanStock 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.
StockReceivedOnDateThis is read-only field. It indicates date on which stock is received For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
NameStringNominal or product name on which stock changes will be applied.
ApplicableOnStringIndicates whether stock management is applicable on nominal or product. Possible values are 'Nominal' or 'Product'

See how IRIS KashFlow works with your business and your books