Invoices

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

NameTypeDescription
NumberNumericUnique 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)
IssuedDateDateDate the invoice was issued. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
DueDateDateDate the invoice should be paid by. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
LastPaymentDateDateLast payment date for the invoice. For e.g. JSON Format : [JSONDATE], XML Format : [XMLDATE]
CustomerCodeStringCode of the customer the invoice is created for
VATAmountNumericTotal VAT amount for the invoice
NetAmountNumericInvoice amount excluding VAT
TotalPaidAmountNumericTotal amount paid in home currency
GrossAmountNumericGross amount
HomeCurrencyGrossAmountNumericGross amount in user’s home currency
CustomerReferenceStringCustomer reference
VATNumberNumericUser’s VAT number
CurrencyObjectCurrency related information such as Code, Name, Exchange Rate
LineItemsCollectionCollection of line items
PaymentLinesCollectionCollection of all payments made
DiscountNumericDiscount assigned to customer
AddressObjectCustomer’s address details
SuppressNumberNumericIndicates whether to use user specified number while creating new invoice
OverdueDaysNumericNumber of days the invoice payment is overdue by
StatusStringIndicates payment status of invoice. Payment status can be Unpaid, Paid, Overpaid, Overdue or NA . NA indicates invoice amount is zero.
PermalinkStringPermanent url of invoice document that can be shared.
PackingSlipPermalinkStringPermanent url of invoice packing slip document that can be shared.
UseCustomDeliveryAddressBooleanSpecifies if value of DeliveryAddress is to be used on packing slip instead of Address.
IsWhtDeductionToBeAppliedBooleanWhether this invoice is eligible for withholding tax deduction.
ReminderLettersCollectionCollection contains sent details for the list of sent Reminder letters. The details will be populated only for an Overdue Invoice.
AutomaticCreditControlEnabledBooleanSpecifies whether automatic credit control is applicable or not.
NextNumberNumericInvoice number of next invoice.
PreviousNumberNumericInvoice number of previous invoice.
PayOnlinePaymentProcessorNumericWhether 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
QuantityNumericUnits of line item
DescriptionStringDescription for this line item
HomeCurrencyRateNumericRate of the line item in home currency.
VATLevelNumericVAT rate applied to the invoice line. This field is read only.
HomeCurrencyVATAmountNumericVAT amount of the invoice line in home currency.
NominalCodeStringNominal code the invoice line is assigned to
ProductCodeNumericUnique code of the product
ProductNameStringName of the product
ProjectNumberNumericUnique identifier of the project associated with the line item
ProjectNameStringName of the project associated with the line item
CustomCheckBoxesCollectionKey value pair of custom checkbox fields
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.
VATExemptNumericVat Exemption value
Tax1AmountNumericAdditional Tax amount to be included if ApplyTax1 is applied
Tax2AmountNumericAdditional Tax amount to be included if ApplyTax2 is applied
Tax3AmountNumericAdditional Tax amount to be included if ApplyTax3 is applied
Tax4AmountNumericAdditional Tax amount to be included if ApplyTax4 is applied
Tax5AmountNumericAdditional Tax amount to be included if ApplyTax5 is applied
ApplyTax1NumericSet to 1 if Tax1Amount is to be applied on this line item
ApplyTax2NumericSet to 1 if Tax2Amount is to be applied on this line item
ApplyTax3NumericSet to 1 if Tax3Amount is to be applied on this line item
ApplyTax4NumericSet to 1 if Tax4Amount is to be applied on this line item
ApplyTax5NumericSet to 1 if Tax5Amount is to be applied on this line item
RateNumericThe rate in quote currency
VATAmountNumericThe VAT amount in quote currency
Payment lines collection parameters
IdNumericUnique Id of the payment line created
InvoiceNumberNumericUnique number of the invoice
DateDateDate of this transaction. For e.g. JSON Format :[JSONDATE], XML Format : [XMLDATE]
NoteStringDescription of this transaction
MethodNumericPayment method Id
AmountNumericAmount that was paid
AccountIdNumericThe bank account id the payment is assigned to
PermalinkStringPermanent url of invoice payment receipt document that can be shared.
BulkIdNumericBulk payment id
ReminderLetter fields
NumberNumericUnique identifier of the reminder letter
IsSentBooleanReminder letter sent status for a particular invoice
SentDateDateDate 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}&filterby={filterby}&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

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. CustomerRef
3. CustomerName
4. InvoiceDate
5. PaymentDueDate
6. GrossAmount
7. NetAmount
8. Status
orderSort direction can be either Asc for ascending or Desc for descending.
filterbyThe 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
projectnumberRetrieve invoices for a particular project. Set to 0 or empty or exclude from URL to exclude this filter
customercodeRetrieve 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

See how KashFlow works with your business and your books