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

GET /api/v1/invoices?filter=overdue

Example 2

Get all invoices from one debitor

GET /api/v1/invoices?client=1337

Example 3

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

GET /api/v1/invoices?filter=open&client=1337

Example 4

Receive all invoices from a specific period.

GET /api/v1/invoices?since=2020-12-15&until=2020-12-31

Example 5

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

GET /api/v1/invoices?since=2020-12-15&until=2020-12-31&sincetype=paiddate

Example 6

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

GET /api/v1/invoices?filter=paid&since=2020-12-15&until=2020-12-31&client=123

Create new invoice

POST /api/v1/invoices/

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',
));