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:

Method(s):

Response Formats:

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.

Request Parameters

Name of the column on which sorting needs to be applied. The acceptable values for this parameter are:1. Number2. Date3. SupplierName4. SupplierReference5. Comment6. 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. All2. Monthly3. Annually4. Weekly5. MultiMonth6. 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.

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.

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.