fbpx

Recurring 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/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

NameTypeDescription
NumberNumericUnique number given to a recurring purchase
DescriptionStringDescription of the recurring purchase
PurchaseDetailsObjectInformation related to the purchase which will be created at scheduled interval
PaymentDetailsObjectInformation 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
FrequencyObjectInformation related to the recurring purchase frequency
DurationObjectInformation related to the duration of the recurring purchase
PurchaseDetails fields
SupplierCodeStringSupplier code for the recurring purchase
SupplierReferenceStringA reference text for the recurring purchase
SupplierNameStringName of the supplier for the recurring purchase
GrossAmountNumericTotal amount of the recurring purchase including VAT, if applicable
NetAmountNumericAmount of the recurring purchase excluding VAT, if applicable
VatAmountNumericVat amount of the recurring purchase , if applicable
LineItemsObject ListInformation 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
TypeStringThe frequency at which the purchase is being created. Possible values are Monthly, Annually, Weekly, MultiMonth and Periodically (repeated after X number of days)
DayOfMonthNumericThe 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.
WeekDayStringDay of the week on which weekly recurring purchases are created. The weekday name needs to be specified in full, say, Wednesday.
MonthsList of stringsList 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)
StartDateDateDate on which creation of periodically recurring purchases is to be started. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
IntervalNumericThe interval in number of days after which periodically recurring purchases are created
Duration fields
TypeStringThe duration for which the system needs to keep creating the recurring purchase for the user. Possible values are RecurIndefinitely, RecurForFixedNumberOfTimes, RecurTillSpecificDate and NA (Disabled)
RecurCountNumericThe number of times a recurring purchase needs to be created in case it is of duration type ‘RecurForFixedNumberOfTimes’
TillSpecificDateDateThe 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

NameDescription
pageThe page number
perpageNumber of records to be fetched
sortbyName 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
orderSort direction can be either Asc for ascending or Desc for descending.
filterbyThe 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.

See how KashFlow works with your business and your books