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/invoices |
Method(s): | get,post,put,delete |
Response Formats: | JSON, XML |
Description: | These methods allow you to retrieve, create, update and delete invoices. The individual resource is identified by the invoice number. So /invoices/100 would return the invoice with number 100. Similarly a PUT to that URL would update invoice 100. A GET to /invoices will return a paginated list of invoices. {number} in the URL would be replaced with the unique number given to invoice. |
Parameters
| Name | Type | Description |
|---|---|---|
| Number | Numeric | Unique invoice identifier. While creating invoice, if a value is passed for this field, then the invoice is created with this number (if it is unique w.r.t the user) |
| IssuedDate | Date | Date the invoice was issued. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE] |
| DueDate | Date | Date the invoice should be paid by. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE] |
| LastPaymentDate | Date | Last payment date for the invoice. For e.g. JSON Format : [JSONDATE], XML Format : [XMLDATE] |
| CustomerCode | String | Code of the customer the invoice is created for |
| VATAmount | Numeric | Total VAT amount for the invoice |
| NetAmount | Numeric | Invoice amount excluding VAT |
| TotalPaidAmount | Numeric | Total amount paid in home currency |
| GrossAmount | Numeric | Gross amount |
| HomeCurrencyGrossAmount | Numeric | Gross amount in user’s home currency |
| CustomerReference | String | Customer reference |
| VATNumber | Numeric | User’s VAT number |
| Currency | Object | Currency related information such as Code, Name, Exchange Rate |
| LineItems | Collection | Collection of line items |
| PaymentLines | Collection | Collection of all payments made |
| Discount | Numeric | Discount assigned to customer |
| Address | Object | Customer’s address details |
| SuppressNumber | Numeric | Indicates whether to use user specified number while creating new invoice |
| OverdueDays | Numeric | Number of days the invoice payment is overdue by |
| Status | String | Indicates payment status of invoice. Payment status can be Unpaid, Paid, Overpaid, Overdue or NA . NA indicates invoice amount is zero. |
| Permalink | String | Permanent url of invoice document that can be shared. |
| PackingSlipPermalink | String | Permanent url of invoice packing slip document that can be shared. |
| UseCustomDeliveryAddress | Boolean | Specifies if value of DeliveryAddress is to be used on packing slip instead of Address. |
| IsWhtDeductionToBeApplied | Boolean | Whether this invoice is eligible for withholding tax deduction. |
| ReminderLetters | Collection | Collection contains sent details for the list of sent Reminder letters. The details will be populated only for an Overdue Invoice. |
| AutomaticCreditControlEnabled | Boolean | Specifies whether automatic credit control is applicable or not. |
| NextNumber | Numeric | Invoice number of next invoice. |
| PreviousNumber | Numeric | Invoice number of previous invoice. |
| PayOnlinePaymentProcessor | Numeric | Whether to use BankPayment or Cardpayment for PayOnline link on PDF which is sent through email. 15 – Bank Payment, 4 – Card Payment, 0 – Means default will be picked (or in case if Settings.UserSettings.CanOverrideDefaultPayOnlineProcessor is equal to 0) |
| Line items collection parameters | ||
| Quantity | Numeric | Units of line item |
| Description | String | Description for this line item |
| HomeCurrencyRate | Numeric | Rate of the line item in home currency. |
| VATLevel | Numeric | VAT rate applied to the invoice line. This field is read only. |
| HomeCurrencyVATAmount | Numeric | VAT amount of the invoice line in home currency. |
| NominalCode | String | Nominal code the invoice line is assigned to |
| ProductCode | Numeric | Unique code of the product |
| ProductName | String | Name of the product |
| ProjectNumber | Numeric | Unique identifier of the project associated with the line item |
| ProjectName | String | Name of the project associated with the line item |
| CustomCheckBoxes | Collection | Key value pair of custom checkbox fields |
| 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. |
| VATExempt | Numeric | Vat Exemption value |
| Tax1Amount | Numeric | Additional Tax amount to be included if ApplyTax1 is applied |
| Tax2Amount | Numeric | Additional Tax amount to be included if ApplyTax2 is applied |
| Tax3Amount | Numeric | Additional Tax amount to be included if ApplyTax3 is applied |
| Tax4Amount | Numeric | Additional Tax amount to be included if ApplyTax4 is applied |
| Tax5Amount | Numeric | Additional Tax amount to be included if ApplyTax5 is applied |
| ApplyTax1 | Numeric | Set to 1 if Tax1Amount is to be applied on this line item |
| ApplyTax2 | Numeric | Set to 1 if Tax2Amount is to be applied on this line item |
| ApplyTax3 | Numeric | Set to 1 if Tax3Amount is to be applied on this line item |
| ApplyTax4 | Numeric | Set to 1 if Tax4Amount is to be applied on this line item |
| ApplyTax5 | Numeric | Set to 1 if Tax5Amount is to be applied on this line item |
| Rate | Numeric | The rate in quote currency |
| VATAmount | Numeric | The VAT amount in quote currency |
| Payment lines collection parameters | ||
| Id | Numeric | Unique Id of the payment line created |
| InvoiceNumber | Numeric | Unique number of the invoice |
| 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 |
| AccountId | Numeric | The bank account id the payment is assigned to |
| Permalink | String | Permanent url of invoice payment receipt document that can be shared. |
| BulkId | Numeric | Bulk payment id |
| ReminderLetter fields | ||
| Number | Numeric | Unique identifier of the reminder letter |
| IsSent | Boolean | Reminder letter sent status for a particular invoice |
| SentDate | Date | Date the reminder letter was sent for a particular invoice. For e.g. JSON Format : 2012-06-28 12:00:00, XML Format : 2012-06-28 12:00:00 |
GET Operation
Returns a paginated list of invoices. To GET list of invoices –URL : /invoices?page={page}&perpage={perpage}&sortby={sortby}&order={order}&statusFilter={statusFilter}&projectnumber={projectnumber}&customercode={customercode}
A paginated list of invoices is returned (ordered by invoice number in ascending order).
Example response for GET of invoice list
{
"Data": [{
"Address": null,
"AutomaticCreditControlEnabled": true,
"Currency": {
"Code": "GBP",
"ExchangeRate": 1.0000,
"Id": 0,
"Name": "British Pounds",
"Symbol": "£",
"DisplaySymbolOnRight": false
},
"CustomerCode": "TCUST01",
"CustomerDiscount": 0,
"CustomerId": 136514,
"CustomerName": "John Smith, CR21 4RT",
"CustomerReference": "",
"DeliveryAddress": null,
"DueDate": "2008-04-08 12:00:00",
"EmailCount": 3,
"GrossAmount": 1100.0000,
"Id": 266693,
"InvoiceInECMemberState": false,
"InvoiceOutsideECMemberState": false,
"IssuedDate": "2008-03-11 12:00:00",
"LineItems": null,
"LastPaymentDate": null,
"NetAmount": 1100.0000,
"Number": 1,
"OverdueDays": 0,
"PaidDate": null,
"PaymentLines": null,
"Status": "Overdue",
"SuppressNumber": 0,
"TotalPaidAmount": 5090.0000,
"UpdateCustomerAddress": false,
"UpdateCustomerDeliveryAddress": false,
"VATAmount": 0.0000,
"VATNumber": null
}, {
"Address": null,
"AutomaticCreditControlEnabled" : false,
"Currency": {
"Code": "GBP",
"ExchangeRate": 1.0000,
"Id": 0,
"Name": "British Pounds",
"Symbol": "£",
"DisplaySymbolOnRight": false
},
"CustomerCode": "TCUST01",
"CustomerDiscount": 0,
"CustomerId": 136514,
"CustomerName": "John Smith, CR21 4RT",
"CustomerReference": "",
"DeliveryAddress": null,
"DueDate": "2008-08-26 12:00:00",
"EmailCount": 0,
"GrossAmount": 1000.0000,
"Id": 490022,
"InvoiceInECMemberState": false,
"InvoiceOutsideECMemberState": false,
"IssuedDate": "2008-04-01 12:00:00",
"LineItems": null,
"LastPaymentDate": null,
"NetAmount": 1000.0000,
"Number": 2,
"OverdueDays": 0,
"PaidDate": null,
"PaymentLines": null,
"Status": "Overdue",
"SuppressNumber": 0,
"TotalPaidAmount": 8000.0400,
"UpdateCustomerAddress": false,
"UpdateCustomerDeliveryAddress": false,
"VATAmount": 0.0000,
"VATNumber": null
}, {
"Address": null,
"AutomaticCreditControlEnabled" : false,
"Currency": {
"Code": "GBP",
"ExchangeRate": 1.0000,
"Id": 0,
"Name": "British Pounds",
"Symbol": "£",
"DisplaySymbolOnRight": false
},
"CustomerCode": "TCUST02",
"CustomerDiscount": 0,
"CustomerId": 280459,
"CustomerName": "KashFlow Customer, CM19 4PT",
"CustomerReference": "",
"DeliveryAddress": null,
"DueDate": "2008-09-16 12:00:00",
"EmailCount": 0,
"GrossAmount": 1512.0000,
"Id": 490024,
"InvoiceInECMemberState": false,
"InvoiceOutsideECMemberState": false,
"IssuedDate": "2008-04-17 12:00:00",
"LineItems": null,
"LastPaymentDate": null,
"NetAmount": 1512.0000,
"Number": 3,
"OverdueDays": 0,
"PaidDate": null,
"PaymentLines": null,
"Status": "Overdue",
"SuppressNumber": 0,
"TotalPaidAmount": 5512.0400,
"UpdateCustomerAddress": false,
"UpdateCustomerDeliveryAddress": false,
"VATAmount": 0.0000,
"VATNumber": null
}],
"MetaData": {
"FirstPageUrl": "https://securedwebapp.com/RestApi/invoices?page=1&perpage=3&sortby=Number&order=Asc",
"LastPageUrl": "https://securedwebapp.com/RestApi/invoices?page=648&perpage=3&sortby=Number&order=Asc",
"NextPageUrl": "https://securedwebapp.com/RestApi/invoices?page=2&perpage=3&sortby=Number&order=Asc",
"PreviousPageUrl": null,
"TotalRecords": 1943
}
}
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. CustomerRef 3. CustomerName 4. InvoiceDate 5. PaymentDueDate 6. GrossAmount 7. NetAmount 8. Status |
| order | Sort direction can be either Asc for ascending or Desc for descending. |
| statusFilter | The list can be filtered by invoice status. Set this parameter to “All” or empty or exclude from the URL if all invoices 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 invoices for a particular project. Set to 0 or empty or exclude from URL to exclude this filter |
| customercode | Retrieve invoices for a particular customer. You don’t need to specify it if you don’t want the invoice list to be filtered by customer code |
To GET a particular invoice with all details –
URL : /invoices/{number}
Example response for GET of invoice
{
"Address": {
"CountryCode": "BR",
"CountryName": "Brazil",
"Line1": 123 Tooley Street,
"Line2": null,
"Line3": null,
"Line4": null,
"PostCode": null
},
"Currency": {
"Code": "GBP",
"ExchangeRate": 1.0000,
"Id": 0,
"Name": "British Pounds",
"Symbol": "£",
"DisplaySymbolOnRight": false
},
"AutomaticCreditControlEnabled": true,
"CustomerDiscount": 0,
"CustomerId": 0,
"CustomerName": null,
"CustomerReference": null,
"DeliveryAddress": null,
"DueDate": "2012-10-09 12:00:00 +05:30",
"EmailCount": 0,
"GrossAmount": 117.5000,
"HomeCurrencyGrossAmount: 117.5000,
"Id": 196172,
"InvoiceInECMemberState": false,
"InvoiceOutsideECMemberState": true,
"IssuedDate": "2012-10-09 12:00:00 +05:30",
"LineItems": [{
"ApplyTax1": false,
"ApplyTax2": false,
"ApplyTax3": false,
"ApplyTax4": false,
"ApplyTax5": false,
"NominalCode": 2341,
"Description": "",
"Number": 1,
"ProductCode": "510",
"ProductName": "Mobile",
"Quantity": 10.0000,
"Rate": 10.0000,
"Tax1Amount": 0.0000,
"Tax2Amount": 0.0000,
"Tax3Amount": 0.0000,
"Tax4Amount": 0.0000,
"Tax5Amount": 0.0000,
"VATAmount": 17.5000,
"VATExempt": 0,
"VATLevel": 17.5000,
"ProjectNumber": 0
}],
"LastPaymentDate": "2012-10-09 12:00:00 +05:30",
"NetAmount": 100.0000,
"Number": 2,
"OverdueDays": 0,
"PaidDate": null,
"PaymentLines": [{
"AccountId": 55166,
"Amount": 110.5000,
"Id": 2,
"InvoiceNumber": 0,
"Date": "2012-10-09 12:00:00 +05:30",
"Method": 409844,
"Note": "Test Payment",
"Permalink": "/v2/documents/invoice/payment/3a22b041-8d45-496a-946d-bd2252a0d28c"
}, {
"AccountId": 55166,
"Amount": 7.0000,
"Id": 53,
"InvoiceNumber": 0,
"Date": "2012-10-09 12:00:00 +05:30",
"Method": 409844,
"Note": "",
"Permalink": "/v2/documents/invoice/payment/3a22b041-8d45-496a-946d-bd2252a0d546"
}],
"Status": "Paid",
"SuppressNumber": 0,
"TotalPaidAmount": 117.5000,
"UpdateCustomerAddress": false,
"UpdateCustomerDeliveryAddress": false,
"UseCustomDeliveryAddress": false,
"VATAmount": 17.5000,
"VATNumber": "",
"PreviousNumber" : 1,
"NextNumber" : 3,
"Permalink": "/v2/documents/invoice/3a22b041-8d45-496a-946d-bd2252a0d28c",
"PackingSlipPermalink": "v2/documents/packingslip/3a22b041-8d45-496a-946d-bd2252a0d28c"
"ReminderLetters": [{
"IsSent": true,
"Number": 3,
"SentDate": "2012-07-30 12:00:00"
}, {
"IsSent": true,
"Number": 1,
"SentDate": "2008-01-02 12:00:00"
}, {
"IsSent": true,
"Number": 2,
"SentDate": "2008-01-02 12:00:00"
}],
"IsWhtDeductionToBeApplied": true,
"PayOnlinePaymentProcessor": 0
}
POST Operation
Creates a new invoice record with the given invoice data using following URL –URL : /invoices
Example request for POST of invoice
Invoice 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. Invoice can be created with multiple invoice line items and same as with payment lines.
{
"Address": {
"CountryCode": "BR",
"Line1": "Address 1",
"Line2": "Address 2",
"Line3": null,
"Line4": null,
"PostCode": null
},
"AutomaticCreditControlEnabled": true,
"Currency": {
"Code": "GBP",
"ExchangeRate": 1.0000,
"Id": 0,
"Name": "",
"Symbol": "",
"DisplaySymbolOnRight": false
},
"CustomerCode": "TEST01",
"CustomerDiscount": 0,
"CustomerId": 0,
"CustomerName": null,
"CustomerReference": null,
"DeliveryAddress": null,
"DueDate": "2012-10-09 12:00:00 +05:30",
"EmailCount": 0,
"ExchangeRate": 1.0000,
"GrossAmount": 117.5000,
"InvoiceInECMemberState": false,
"InvoiceOutsideECMemberState": true,
"IssuedDate": "2012-10-09 12:00:00 +05:30",
"LineItems": [{
"ApplyTax1": false,
"ApplyTax2": false,
"ApplyTax3": false,
"ApplyTax4": false,
"ApplyTax5": false,
"NominalCode": 2341,
"Description": "Created through rest api",
"Number": 0,
"ProductCode": "",
"Quantity": 10.0000,
"Rate": 10.0000,
"Tax1Amount": 0.0000,
"Tax2Amount": 0.0000,
"Tax3Amount": 0.0000,
"Tax4Amount": 0.0000,
"Tax5Amount": 0.0000,
"VATAmount": 17.5000,
"VATExempt": 0,
"VATLevel": 17.5000,
"ProjectNumber": 0
}],
"LastPaymentDate": "2012-10-09 12:00:00 +05:30",
"NetAmount": 100.0000,
"Number": 2,
"OverdueDays": 0,
"PaidDate": null,
"PaymentLines": [{
"AccountId": 55166,
"Amount": 110.5000,
"InvoiceNumber": 0,
"Date": "2012-10-09 12:00:00 +05:30",
"Method": 409844,
"Note": "Test Payment"
}, {
"AccountId": 55166,
"Amount": 7.0000,
"InvoiceNumber": 0,
"Date": "2012-10-09 12:00:00 +05:30",
"Method": 409844,
"Note": ""
}],
"Status": "Paid",
"SuppressNumber": 0,
"TotalPaidAmount": 117.5000,
"UpdateCustomerAddress": false,
"UpdateCustomerDeliveryAddress": false,
"UseCustomDeliveryAddress": false,
"VATAmount": 17.5000,
"VATNumber": "",
"PayOnlinePaymentProcessor": 0
}
PUT Operation
Updates an invoice record of the invoice number provided in URL –URL : /invoices/{number}
Example request for PUT of invoice
To update invoice you need to provide whole invoice data, same as response of GET of that invoice. And update the required data field or if you want to add line item or payment line to an existing invoice.
To create a new line item, item with a number 0 should be specified.
If existing line item(s) is/are not passed in PUT request body, then those line item(s) are deleted from DB.
{
"Address": {
"CountryCode": "BR",
"Line1": "Address updated",
"Line2": "Address 2 updated",
"Line3": "Address 3 updated",
"Line4": null,
"PostCode": null
},
"AutomaticCreditControlEnabled": true,
"Currency": {
"Code": "GBP",
"ExchangeRate": 1.0000,
"Id": 0,
"Name": "",
"Symbol": "",
"DisplaySymbolOnRight": false
},
"CustomerCode": "TEST01",
"CustomerDiscount": 0,
"CustomerId": 0,
"CustomerName": null,
"CustomerReference": null,
"DeliveryAddress": null,
"DueDate": "2012-10-09 12:00:00 +05:30",
"EmailCount": 0,
"ExchangeRate": 1.0000,
"GrossAmount": 117.5000,
"Id": 196172,
"InvoiceInECMemberState": false,
"InvoiceOutsideECMemberState": true,
"IssuedDate": "2012-10-09 12:00:00 +05:30",
"LineItems": [{
"ApplyTax1": false,
"ApplyTax2": false,
"ApplyTax3": false,
"ApplyTax4": false,
"ApplyTax5": false,
"NominalCode": 2341,
"Description": "Description updated through PUT operation",
"Number": 1,
"ProductCode": "",
"Quantity": 10.0000,
"Rate": 10.0000,
"Tax1Amount": 0.0000,
"Tax2Amount": 0.0000,
"Tax3Amount": 0.0000,
"Tax4Amount": 0.0000,
"Tax5Amount": 0.0000,
"VATAmount": 17.5000,
"VATExempt": 0,
"VATLevel": 17.5000,
"ProjectNumber": 0
}],
"LastPaymentDate": "2012-10-09 12:00:00 +05:30",
"NetAmount": 100.0000,
"Number": 2,
"OverdueDays": 0,
"PaidDate": null,
"PaymentLines": [{
"AccountId": 55166,
"Amount": 110.5000,
"Id": 2,
"InvoiceNumber": 0,
"Date": "2012-10-09 12:00:00 +05:30",
"Method": 409844,
"Note": "Test Payment"
}, {
"AccountId": 55166,
"Amount": 7.0000,
"Id": 53,
"InvoiceNumber": 0,
"Date": "2012-10-09 12:00:00 +05:30",
"Method": 409844,
"Note": ""
}],
"Status": "Paid",
"SuppressNumber": 0,
"TotalPaidAmount": 117.5000,
"UpdateCustomerAddress": false,
"UpdateCustomerDeliveryAddress": false,
"UseCustomDeliveryAddress": false,
"VATAmount": 17.5000,
"VATNumber": "",
"PayOnlinePaymentProcessor": 0
}
DELETE Operation
Deletes the invoice with the number provided in the URL.URL : /invoices/{number}
PUT Operation
Updates address of all invoices of specified customer-URL : /invoices/address?customercode={customercode}
{customercode} in the URL will be replaced by code of the customer whose invoices’ address needs to be changed.
Example request
{
"Line1": "Address updated",
"Line2": "Address 2 updated",
"Line3": "Address 3 updated",
"Line4": "Address 4 updated",
"PostCode": "Post Code Updated",
"CountryCode": "GB"
}
Response : 200 OK