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/recurringpurchases |
Method(s): | get, delete, put, post |
Response Formats: | JSON, XML |
Description: | This method allows you to retrieve the list of recurring purchases setup for a user,create a new recurring purchase, update an existing recurring purchase and delete recurring purchase. |
Parameters
| Name | Type | Description |
|---|---|---|
| Number | Numeric | Unique number given to a recurring purchase |
| Description | String | Description of the recurring purchase |
| PurchaseDetails | Object | Information related to the purchase which will be created at scheduled interval |
| PaymentDetails | Object | Information related to the payment details of the recurring purchase. The fields of this object are same as purchase payment line items. For rest of the payment fields refer Purchase documentation |
| Frequency | Object | Information related to the recurring purchase frequency |
| Duration | Object | Information related to the duration of the recurring purchase |
| PurchaseDetails fields | ||
| SupplierCode | String | Supplier code for the recurring purchase |
| SupplierReference | String | A reference text for the recurring purchase |
| SupplierName | String | Name of the supplier for the recurring purchase | GrossAmount | Numeric | Total amount of the recurring purchase including VAT, if applicable |
| NetAmount | Numeric | Amount of the recurring purchase excluding VAT, if applicable |
| VatAmount | Numeric | Vat amount of the recurring purchase , if applicable |
| LineItems | Object List | Information related to the line items of the recurring purchase. The fields of this object are same as purchase line items.For more information on these fields refer Purchase documentation |
| Frequency fields | ||
| Type | String | The frequency at which the purchase is being created. Possible values are Monthly, Annually, Weekly, MultiMonth and Periodically (repeated after X number of days) |
| DayOfMonth | Numeric | The day of the month on which the recurring purchase needs to be created. The value should be between 1 and 28 for frequency type ‘Monthly’ or ‘MultiMonth’. For an ‘Annually’ recurring purchase, the value of this field should be a valid date of the month specified. |
| WeekDay | String | Day of the week on which weekly recurring purchases are created. The weekday name needs to be specified in full, say, Wednesday. |
| Months | List of strings | List of months in which multi-monthly recurring purchases are created. If a single month name needs to be specified, like in the case of ‘Annually’ frequency, this array should contain only 1 month name. The month name should be a string (full name of month, say, January) |
| StartDate | Date | Date on which creation of periodically recurring purchases is to be started. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE] |
| Interval | Numeric | The interval in number of days after which periodically recurring purchases are created |
| Duration fields | ||
| Type | String | The duration for which the system needs to keep creating the recurring purchase for the user. Possible values are RecurIndefinitely, RecurForFixedNumberOfTimes, RecurTillSpecificDate and NA (Disabled) |
| RecurCount | Numeric | The number of times a recurring purchase needs to be created in case it is of duration type ‘RecurForFixedNumberOfTimes’ |
| TillSpecificDate | Date | The specific date till when the recurring purchase need to be created in case it is of duration type ‘RecurTillSpecificDate’. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE] |
Sorting of line items
1. The ‘Number’ field of a recurring purchase line item also represents the sort order.
2. For re-arranging line items, their position in the LineItems list needs to changed.
GET Operation
GET of recurring purchases returns list of recurring purchases setup for the user.URL : /recurringpurchases?page={page}&perpage={perpage}&sortby={sortby}&order={order}&filterby={filterby}
Example response for GET of list of recurring purchases
{
"Data": [
{
"Description": "Monthly Repeated Purchase",
"Duration": {
"Type": "RecurTillSpecificDate"
},
"Frequency": {
"DayOfMonth": 8,
"Months": [
"August"
],
"Type": "MultiMonth"
},
"PurchaseDetails": {
"SupplierCode": "YAHO01",
"SupplierName": "Yahoo",
"SupplierReference": "",
"GrossAmount": 172.8,
"LineItems": null,
"NetAmount": 0,
"PaymentDetails": null,
"VATAmount": 0
},
"Number": 1
},
{
"Description": "",
"Duration": {
"Type": "RecurIndefinitely"
},
"Frequency": {
"DayOfMonth": 4,
"Months": [
"March",
"May"
],
"Type": "MultiMonth"
},
"PurchaseDetails": {
"SupplierCode": "QUCI01",
"SupplierName": "QucikEC test 2",
"SupplierReference": "",
"GrossAmount": 0,
"LineItems": null,
"NetAmount": 0,
"PaymentDetails": null,
"VATAmount": 0
},
"Number": 15
}
],
"MetaData": {
"FirstPageUrl": "/v2/recurringpurchases?page=1&perpage=2&sortby=SupplierName&order=Desc",
"LastPageUrl": "/v2/recurringpurchases?page=9&perpage=2&sortby=SupplierName&order=Desc",
"NextPageUrl": "/v2/recurringpurchases?page=2&perpage=2&sortby=SupplierName&order=Desc",
"PreviousPageUrl": null,
"TotalRecords": 17
}
}
Request Parameters
| Name | Description |
|---|---|
| page | The page number |
| perpage | Number of records to be fetched |
| sortby | Name of the column on which sorting needs to be applied. The acceptable values for this parameter are: 1. Number 2. Date 3. SupplierName 4. SupplierReference 5. Comment 6. Amount |
| order | Sort direction can be either Asc for ascending or Desc for descending. |
| filterby | The list can be filtered by recurring purchase frequency type. Set this parameter to “All” or empty or exclude from the URL if all recurring purchases are to be retrieved. The acceptable values for this parameter are: 1. All 2. Monthly 3. Annually 4. Weekly 5. MultiMonth 6. Periodically |
To get details of a particular recurring purchase with all details, use below URL. The ‘Number’ field of each line item not only identifies a line item uniquely, but also represents its ‘sort’ order. The ‘sort’ order decides the position of an item in the list of line items on UI.
URL : /recurringpurchase/{number}
Example response for GET of recurring purchase
{
"Description": "MonthlyInterest",
"Duration": {
"Type": "NA"
},
"Frequency": {
"DayOfMonth": 12,
"Months": ["May"],
"Type": "Annually"
},
"Number": 1,
"PurchaseDetails": {
"GrossAmount": 0.0000,
"LineItems": [{
"Description": "MonthlyInterest",
"HomeCurrencyRate": 0,
"HomeCurrencyVATAmount": 0,
"NominalCode": 7502,
"Number": 1,
"ProductCode": "",
"ProductName": "",
"Quantity": 1000.0000,
"Rate": 0.00,
"TaxCode": "",
"VATAmount": 0.00,
"VATExempt": false,
"VATLevel": 17.5000,
"ProjectNumber": 0
}],
"NetAmount": 0.000000,
"PaymentDetails": null,
"SupplierCode": "08C",
"SupplierName": "Honda Suppliers",
"SupplierReference": "",
"VATAmount": 0.00
}
}
POST Operation
POST of recurring purchases creates a recurring purchase for the user.URL : /recurringpurchases
Purchase can be created with or without line items. Recurring purchase can be created with multiple purchase line items but only one payment line can accompany a recurring purchase. If line items are specified, it must be ensured that the ‘Number’ field for each one of them is 0. The order in which the line items are placed in the LineItems list decides their sort order.
Note: Recurring purchases are always created in home currency.
Example request for POST of recurring purchase
{
"Description":"Description",
"Duration":{
"RecurCount":12,
"Type":"RecurForFixedNumberOfTimes"
},
"Frequency":{
"DayOfMonth":10,
"Months":[
"February",
"January",
"March"
],
"Type":"MultiMonth"
},
"Number":9,
"PurchaseDetails":{
"GrossAmount":1650.0000,
"LineItems":[
{
"Description":"",
"HomeCurrencyRate":0,
"HomeCurrencyVATAmount":0,
"NominalCode":10,
"Number":0,
"ProductCode":"",
"ProductName":"",
"Quantity":2.0000,
"Rate":550.00,
"TaxCode":"",
"VATAmount":0.00,
"VATExempt":false,
"VATLevel":0.0000,
"ProjectNumber":0
},
{
"Description":"",
"HomeCurrencyRate":0,
"HomeCurrencyVATAmount":0,
"NominalCode":10,
"Number":0,
"ProductCode":"",
"ProductName":"",
"Quantity":1.0000,
"Rate":550.00,
"TaxCode":"",
"VATAmount":0.00,
"VATExempt":false,
"VATLevel":0.0000,
"ProjectNumber":0
}
],
"NetAmount":1650.000000,
"PaymentDetails":{
"AccountId":248307,
"Amount":50.0000,
"Method":727693,
"Note":""
},
"SupplierCode":"01",
"SupplierName":"01",
"SupplierReference":"",
"VATAmount":0.00
}
}
PUT Operation
PUT of recurring purchases updates a recurring purchase for the user.URL : /recurringpurchases/{number}
where {number} refers to the unique number of a recurring purchase
To update a recurring purchase, you need to provide whole recurring purchase data, same as response of GET of that recurring purchase. And update the required data field or if you want to add line item or payment data to an existing recurring purchase.
To create a new line item, item with a ‘Number’ 0 should be specified.
While updating a recurring purchase, if an old ‘Number’ is not found in the request body, the line item associated with this ‘Number’ is deleted.
The number of a recurring purchase can be updated, provided the new number is unique for the user, by specifying the new number in the ‘Number’ field of the PUT request body.
Example request for PUT of recurring purchase
{
"Description":"Description",
"Duration":{
"RecurCount":12,
"Type":"RecurForFixedNumberOfTimes"
},
"Frequency":{
"DayOfMonth":10,
"Months":[
"February",
"January",
"March"
],
"Type":"MultiMonth"
},
"Number":9,
"PurchaseDetails":{
"GrossAmount":1100.0000,
"LineItems":[
{
"Description":"",
"HomeCurrencyRate":0,
"HomeCurrencyVATAmount":0,
"NominalCode":10,
"Number":2,
"ProductCode":"",
"ProductName":"",
"Quantity":2.0000,
"Rate":550.00,
"TaxCode":"",
"VATAmount":0.00,
"VATExempt":false,
"VATLevel":0.0000,
"ProjectNumber":0
}, {
"Description":"",
"HomeCurrencyRate":0,
"HomeCurrencyVATAmount":0,
"NominalCode":10,
"Number":1,
"ProductCode":"",
"ProductName":"",
"Quantity":1.0000,
"Rate":550.00,
"TaxCode":"",
"VATAmount":0.00,
"VATExempt":false,
"VATLevel":0.0000,
"ProjectNumber":0
}
],
"NetAmount":1100.000000,
"PaymentDetails":{
"AccountId":248307,
"Amount":50.0000,
"BulkId":0,
"BulkPaymentNumber":0,
"Id":0,
"Method":727693
},
"SupplierCode":"01",
"SupplierName":"01",
"SupplierReference":"",
"VATAmount":0.00
}
}DELETE Operation
Deletes the recurring purchase with the number provided in the URL.URL : /recurringpurchases/{number}
{number} would be replaced by valid recurring purchase number.