Invoices API

To manage your invoices, you can use the following commands.

Description	Method	URL
Get all invoices	GET	/api/v1/invoices
Get one invoice	GET	/api/v1/invoices/{id}
Create new invoice	POST	/api/v1/invoices/
Delete a invoice	DELETE	/api/v1/invoices/{id}

All attributes used for invoices

Attribute	Type	Note
invoicenr	string	Invoice number including layout When posting an invoice, do not specify or define this attribute. If you really want to define the invoice number, please include the invoice number as an integer number without any prefix layout. So to create INVOICE00023, please send us 23 as integer. Use this with caution! When used wrong it can ruin your administration and invoice numbers. Only use this when absolutely necessary.
reference	object	Contains reference lines on the invoice. 'line1', 'line2', 'line3'. All are strings.
lines	array	All invoice lines on the invoice Per line: 'amount' 'amount_desc' 'description' 'tax_rate' 'price' 'discount_pct' (discount percentage) 'tax_country' (boolean, input only)* 'linetotal' (read only) if you want to use a foreign tax for this line, set this to true. Read more To use text lines on an invoice, only supply 'description' and do not use the other fields. You can include specific line types by simply specifying the 'type' field when adding a line. There are four available types: - 'subtotal': This type adds a subtotal line. - 'page_separator': It initiates a new page. - 'bundle_start': This type marks the beginning of a pricing bundle. - 'bundle_end': It signifies the conclusion of a pricing bundle. See the example below for more info.
profile	id	The ID of the used profile. Default is default profile
category	id	The ID of the category. Use the categories api to retrieve a list of categories.
discounttype	string(10)	The type of discount. 'amount' or 'percentage'
discount	float	If 'discounttype' is amount, then this is the amount of discount set on the invoice. If 'discounttype' is set to 'percentage', this is the discount percentage set.
paymentcondition	string	The payment condition set on the invoice. Default is the payment condition set in the application.
paymentperiod	integer	Term of payment in days. Default is the payment period set with the client.
paymentmethod	string(10)	How the invoice is going to be paid. 'bank': normal bank account transfer 'autocollect': the invoice will be collected (incasso). When using 'autocollect', ensure that the client has collection enabled and is set up correctly.
collectionread only	boolean	If invoice is an automatic collection
taxesread only	array	All taxes defined in the invoice Per taxes: 'rate': tax rate 'sum': taxes on the invoice for this rate 'sum_of': amount where this taxes is relates to
taxread only	float	Total of all taxes on this invoice
totalintaxread only	float	Invoice total including taxes
tax_typeread only	string	Will show if the invoice lines are excluding or including tax: Values are: 'intax' or 'extax'
languageread only	string	The language used in the document. 'nl': dutch 'en': english 'de': german 'fr': france 'es': spanish 'it': italian
tax_shiftedread only	boolean	If the tax on the invoice is shifted to the receiver
clientnr	integer	Client number
contactread only	string(50)
companyread only	string(50)
addressread only	string(50)
zipcoderead only	string(7)
cityread only	string(50)
countryread only	integer or string	Country id. You can get a list of country id's with the function api/v1/countrylist. When creating or updating a client, you can supply a country id or a country name. We'll then try to find the id of the country you supplied.
phoneread only	string(13)
mobileread only	string(13)
invoicenote	string	A note that is saved with the invoice
sent	date	The date the invoice is sent
uncollectibleread only	date	The date when the invoice is marked as uncollectible
lastreminderread only	date	The date when the last reminder was sent
openread only	float	The amount that is still open on the invoice. If this amount is 0, then the invoice is paid. If it is negative, there is paid more than the invoice amount.
paiddate	date	The date of the last received payment
payment_urlread only	string	The complete URL where the invoice can be paid
duedateread only	date	The duedate of the invoice. This is the sent-date + the payment period in days.
historyread only	array	The actions taken by the user or the system for this invoice

Special filtering for invoices

The invoices have a special filter to quickly access different invoice types, like invoices that are overdue, date ranges or debitor numbers. Possible filter options:

Description	Method	URL
Get open invoice (all invoices that are not fully paid yet)	GET	{url}?filter=open
Get overdue invoices	GET	{url}?filter=overdue
Get sent invoices	GET	{url}?filter=sent
Get partly paid invoices	GET	{url}?filter=partly
Get invoices with too much paid	GET	{url}?filter=toomuch
Get paid invoices	GET	{url}?filter=paid
Get invoices that couldn't be collected	GET	{url}?filter=uncollectible
Since date	GET	{url}?since=YYYY-MM-DD
Until dateoptional	GET	{url}?until=YYYY-MM-DD
Filter on paid date instead of invoice dateoptional	GET	{url}?sincetype=paidddate
Get invoices from a single debitor	GET	{url}?client={client number}

Example 1

Receive all invoices that are overdue

Example 2

Get all invoices from one debitor

Example 3

Get all open invoices that are not paid yet from one debitor

Example 4

Receive all invoices from a specific period.

Example 5

Receive all invoices from a specific period based on the invoice paid date.

Example 6

Receive all paid invoices from a specific period and from a specific client

Create new invoice

When posting a new invoice, there are several extra attributes needed besides the ones shown above.

Attribute	Type	Note
actionrequired	string(6)	Define the action what we should do with your request. 'send': send the invoice 'save': save the invoice as a draft 'repeat': plan a repeating invoice
sendmethod	string(11)	How to send the invoice to the receiver. Required when you use the action 'send' 'mail': print the invoices yourself. We'll send you the invoice number so you can execute a command to retrieve the PDF if you need so. 'email': send invoices through e-mail. It will be sent immediately. 'printcenter': send invoice through the printcenter.
savename	string(20)	When the action is 'save' or 'repeat' you must supply a savename. We'll save the invoice under that name.
overwrite_if_exist	boolean	If a savename already exists, it will not be overwritten unless this attribute is set to 'true'. Default is 'false'.
convert_prices_to_euro	boolean	When this option is set to 'true' we will convert all the given prices on the invoices to euro, based on the currency set in the selected client and the invoice date (to retrieve the current exchange rate).
alreadypaid	float or string	Mark a part of the invoice as already paid. We'll place an extra line in the PDF that says that a part of the invoice is already paid. We'll also register that a part is paid in your account. Supply the amount in 'float'. You can also supply 'full' as a value. We will mark the invoice total as amount.
alreadypaidmethod	string(32)	Enter a string of the payment method. It can be anything you want, for example: 'Pin', 'Cash', 'MasterCard', 'Gift from Santa', etc.

When planning a repeating invoice with the action 'repeat' there are several fields also needed for us to process the invoice.

Attribute	Type	Note
initialdaterequired	date	Date when the first invoice must be sent. Please use YYYY-MM-DD
finalsenddateoptional	date	Date when the last invoice must be sent. After this date the repeating invoice entry is deleted. Please use YYYY-MM-DD
frequencyrequired	string(10)	The frequency when the invoice must be sent. Based on the initialdate. Possible options: 'weekly', 'monthly', 'quarterly', 'halfyearly', 'yearly', 'biweekly', 'bimonthly', 'fourweekly', 'twoyearly', 'threeyearly'
repeattyperequired	string(6)	The repeating invoice can be sent automatically or manually. If 'auto' is defined, the invoice will be sent at the designated time. If 'manual' is defined, a notification will be sent to the user's dashboard or through a push notification when it is time to send the invoice.

Example 1 - sending an invoice through the e-mail

In this example we'll send an invoice through the e-mail. When this command is executed, the e-mail is immediately sent.

$request->buildPostBody(array(
  'clientnr' => 218064,
  'reference' => array(
    'line1' => 'Soundboard Setup',
    'line2' => 'Thank you for the order',
    'line3' => 'Our reference is: 3993029/11BD'
  ),
  'lines' => array(
    array('amount' => 50,
      'amount_desc' => 'panels',
      'description' => 'Sound buttons',
      'tax_rate' => 21,
      'price' => 5.952
    ),
    array('amount' => 1,
      'amount_desc' => '',
      'description' => 'Wooden case',
      'tax_rate' => 21,
      'discount_pct' => 25,
      'price' => 500
    ),
    array('amount' => 10,
      'amount_desc' => 'hours',
      'description' => 'Support',
      'tax_rate' => 9,
      'price' => 62.5
    ),
    array('description' => 'This is a textline')),
    'discount' => 10,
    'discounttype' => 'percentage',
    'action' => 'send',
    'sendmethod' => 'email'
));

Or as a JSON:

{
  "clientnr": 218064,
  "reference": {
    "line1": "Soundboard Setup",
    "line2": "Thank you for the order",
    "line3": "Our reference is: 3993029/11BD"
  },
  "lines": [
    {
      "amount": 50,
      "amount_desc": "panels",
      "description": "Sound buttons",
      "tax_rate": 21,
      "price": 5.952
    },
    {
      "amount": 1,
      "amount_desc": "",
      "description": "Wooden case",
      "tax_rate": 21,
      "discount_pct": 25,
      "price": 500
    },
    {
      "amount": 10,
      "amount_desc": "hours",
      "description": "Support",
      "tax_rate": 9,
      "price": 62.5
    },
    {
      "description": "This is a textline"
    }
  ],
  "discount": 10,
  "discounttype": "percentage",
  "action": "send",
  "sendmethod": "email"
}

Example 2 - save a draft invoice

In this example, we'll create an invoice and then save it as a draft so we can edit it later on in the web application.

$request->buildPostBody(array(
  'clientnr' => 218064,
  'lines' => array(
    array('amount' => 50,
      'amount_desc' => 'panels',
      'description' => 'Sound buttons',
      'tax_rate' => 21,
      'price' => 5.952,
    )
  ),
  'discount' => 10,
  'discounttype' => 'percentage',
  'action' => 'save',
  'savename' => 'my_invoice'
));

Example - plan a repeating invoice

In this example, we'll create an invoice and then plan it as a repeating invoice.

$request->buildPostBody(array(
  'clientnr' => 218064,
  'lines' => array(
    array('amount' => 50,
      'amount_desc' => 'panels',
      'description' => 'Sound buttons',
      'tax_rate' => 21,
      'price' => 5.952,
    )
  ),
  'discount' => 10,
  'discounttype' => 'percentage',
  'action' => 'repeat',
  'savename' => 'planning_invoice',
  'initialdate' => '2020-03-07',
  'finalsenddate' => '2022-01-01',
  'frequency' => 'monthly',
  'repeattype' => 'auto'
));

Example 3 - send an invoice and mark it immediately as paid

In this example, we'll send an invoice and mark it directly as paid. Please note: marking the invoice as paid doesn't change anything to the invoice email text that is sent. Make sure the email text contains information that the invoice is already paid or use the sendmethod 'mail'. This way, no email is sent. You can create an own email in your program and retrieve the invoice pdf file with our api.

$request->buildPostBody(array(
  'clientnr' => 218064,
  'lines' => array(
    array('amount' => 50,
      'amount_desc' => 'panels',
      'description' => 'Sound buttons',
      'tax_rate' => 21,
      'price' => 5.952
  ),
  'action' => 'send',
  'sendmethod' => 'mail',
  'paiddate' => '2020-09-21'
));

Example 4 - send an invoice and mark a part as paid

In this example, we'll send an invoice and mark a part of the invoice as paid (like when the customer already paid a part of the invoice up front). Please note: marking the invoice as paid doesn't change anything to the invoice email text that is sent. Make sure the email text contains information that the invoice is already paid or use the sendmethod 'mail'. This way, no email is sent. You can create an own email in your program and retrieve the invoice pdf file with our api.

$request->buildPostBody(array(
  'clientnr' => 218064,
  'lines' => array(
    array('amount' => 50,
      'amount_desc' => 'panels',
      'description' => 'Sound buttons',
      'tax_rate' => 21,
      'price' => 5.952
    )
  ),
  'action' => 'send',
  'sendmethod' => 'mail',
  'alreadypaid' => 150, // use 'full' for the invoice total
  'alreadypaidmethod' => 'Pin',
));

Example 5 - use special line types

In this illustration, we will generate an invoice featuring both invoicing lines and distinctive line types.

$request->buildPostBody(array(
  'clientnr' => 218064,
  'lines' => array(
    array('amount' => 50,
      'amount_desc' => 'panels',
      'description' => 'Sound buttons',
      'tax_rate' => 21,
      'price' => 5.952
    ),
    array('amount' => 10,
      'amount_desc' => 'hours',
      'description' => 'Support',
      'tax_rate' => 9,
      'price' => 62.5
    ),
    array(
      'type' => 'subtotal' // you can use 'subtotal', 'page_separator', 'bundle_start' and 'bundle_end'
    )
    array('amount' => 1,
      'amount_desc' => '',
      'description' => 'Wooden case',
      'tax_rate' => 21,
      'discount_pct' => 25,
      'price' => 500
    ),

  ),
  'action' => 'send',
  'sendmethod' => 'mail',
  'alreadypaid' => 150, // use 'full' for the invoice total
  'alreadypaidmethod' => 'Pin',
));