Items from the “invoices” domain represent an invoice or credit note. With an invoice the total amount is positive, with a credit note the total amount is negative.
Structure of URL’s:
/api/v1/invoices: Billing data
.be/api/v1/invoices/3003: Invoice with ID 3003
/api/v1/invoices/3003/items: Items of invoice with ID 3003
/api/v1/invoices/3003/items/4005: Item with ID 4005 of invoice with ID 3003
/api/v1/invoices/3003/remarks: Comments of invoice with ID 3003
/api/v1/invoices/3003/remarks/5010: Note with ID 5010 of invoice with ID 3003
/api/v1/invoices/3003/payments: Payments of invoice with ID 3003
/api/v1/invoices/3003/payments/5020: Payment with ID 5020 of invoice with ID 3003
/api/v1/invoices/3003/costs: Reminder fee of invoice ID 3003
/api/v1/invoices/3003/costs/5030: Reminder fee with ID 5030 van factuur met ID 3003
/api/v1/invoices/3003/events: Invoice events with ID 3003
/api/v1/invoices/3003/events/5030: ID 5030 invoice event with ID 3003
/api/v1/uploads: File Uploads/Attachments
Domain : invoices
| Field name | Type | Description | Example |
|---|---|---|---|
| invoice_id | int | Unique ID of the invoice. Generated by the system. Mandatory to enter in URL (except for creation). | 3003 |
| uri | text | URL to invoice. Generated by the system. To be used when addressing invoice via the API. | – |
| external_invoice_id | text | (Unique) ID of the invoice that can be set by a third party. Maximum 50 characters long. Uniqueness of value is not enforced. | Invoice-0983984 |
| client_id | int | Unique ID of the customer. Mandatory to give up at creation. | 1001 |
| client_uri | text | URL to the customer. Generated by the system. To be used when addressing the customer via the API. | – |
| client_name | text | Name of the customer. Automatically taken from the customer data if not specified. | IT Services BVBA |
| client_attention | text | Attn. from the customer. Automatically taken from the customer data if not specified. | Adminstration Department |
| type | text | Type of invoice. Possible values: 'creditnote' or 'invoice'. Determined by the system and cannot be provided by the user. | invoice |
| number | text | Unique number of the invoice as shown on the invoice. Generated if not given. Maximum 255 characters long. | INV2012-001 |
| layout_id | int | Unique ID of the layout. If not specified, the default layout is automatically determined. May be blank if no layout has been set for the account. | 8001 |
| reference | text | Self-specified reference of the invoice. Not required. Maximum 250 characters long. | ID123456789 |
| date | date | Date of creation of the invoice. Generated if not given. Format YYYY-MM-DD. | 2012-02-15 |
| date_delivery | date | Date of delivery of goods/services on the invoice. Generated if not given. Format YYYY-MM-DD. | 2012-02-15 |
| status | text | Status of the invoice. Possible values: 'open', 'overdue', 'closed'. Determined by the system and cannot be specified by itself. | open |
| days_due | int | Payment term in number of days of the invoice. If not specified, the defaults are taken according to settings. Maximum value 999 days. If 0, there is no payment term. Not applicable for credit note (type = 'creditnote'). | 10 |
| days_overdue | int | Number of days that payment term has already been exceeded compared to the current date. Only shown if status 'overdue'. Generated by the system and cannot be specified by itself. Not applicable for credit note. | 0 |
| date_overdue | date | Date on which the payment term expired. Is automatically determined by means of the field 'date' and 'days_due'. Not applicable for credit note. | 2012-02-25 |
| billing_address | Address | Billing address of the customer. Automatically taken from the customer data if not specified. | – |
| delivery_address | Address | Shipping address of the customer. Automatically taken from the customer data if not specified. | – |
| site_address | Address | Customer's site address. Automatically taken from the customer data if not specified. | – |
| discount_percentage | float | Discount percentage that applies to the entire invoice. Amount must be between 0 and 100. Numbers up to 2 digits after the comma are allowed. If not specified, this value is 0. | 5 |
| cash_discount_percentage | float | Discount percentage financial discount that applies to the entire invoice. Amount must be between 0 and 100. Numbers up to 2 digits after the comma are allowed. If not specified, this value is 0. If larger than 0, the field 'cash_discount_days_valid' is mandatory. | 2 |
| cash_discount_days_valid | int | Number of days that the financial discount is valid. Amount must be between 0 and 100. Only whole numbers are allowed. If not specified, this value is 0. This field can only be specified if the field 'cash_discount_percentage' was also specified. | 8 |
| cash_discount_date_valid | date | Number of days that the financial discount is valid. Amount must be between 0 and 100. Only whole numbers are allowed. If not specified, this value is 0. This field can only be specified if the field 'cash_discount_percentage' was also specified. | 2012-02-23 |
| currency | text | The currency of the invoice. This value must be part of an illustrative list of the supported currencies. The value is 3 characters long and always in capitals. If not specified, EUR is used. | EUR |
| exchange_rate | number | The exchange rate to convert the amounts on the invoice to EUR. | 1 |
| show_tax_for_exchange_rate | text | Show the VAT converted to EURO on the invoice if another currency is used (as required by law). Can have a value of 'yes' or 'no'. If empty, the default value is 'yes'. | yes |
| language | text | The language in which the invoice will be created. This value can contain 'dutch', 'french', 'english' or 'german' but can also be empty. If empty (= default value) the default language (dutch) will be used. | dutch |
| tax_calculation | text | The vat calculation method of the invoice. Possible values: 'total', 'item'. By default, 'total' is used. For calculation method 'total' the VAT is calculated on the total amount of the invoice, for calculation method 'item' the VAT is calculated per invoice line. Switching between the calculation method can give rounding differences. If 'tax_included'='yes', only 'item' is a valid value. | total |
| tax_included | text | Indicates whether or not the amounts of the invoice were declared including VAT and are therefore printed including VAT. Can have a value of 'yes' or 'no'. If empty, the default value is determined as set for the account (default 'no'). | no |
| items | list | List of invoice items. | – |
| discount_total_without_tax | float | Total amount of the discount granted on the invoice total without taking VAT into account. Calculated automatically and cannot be specified yourself. | 10.00 |
| total_refundable_deposit | float | Total amount of invoice lines with refundable packaging (tax_rate_special_status = DR). Calculated automatically and cannot be specified yourself. | 5.00 |
| total_without_tax | float | Total amount over all invoice items without taking VAT into account. Any discounts (discount_total_without_tax) and refundable packaging (total_refundable_deposit) are already included in this total. Calculated automatically and cannot be specified yourself. | 200.00 |
| tax_rate_1 | float | 1st VAT percentage that can be used on the invoice. Is copied from the settings during creation and cannot be specified yourself. | 21 |
| total_tax_1 | float | Total amount of VAT according to 1st VAT percentage over all invoice items. Calculated automatically and cannot be specified yourself. | 42.00 |
| tax_rate_2 | float | 2nd VAT percentage that can be used on the invoice. Is copied from the settings during creation and cannot be specified yourself. | 12 |
| total_tax_2 | float | Total amount of VAT according to 2nd VAT percentage over all invoice items. Calculated automatically and cannot be specified yourself. | 0.00 |
| tax_rate_3 | float | 3rd VAT percentage that can be used on the invoice. Taken from the settings during creation and cannot be specified by yourself. | 6 |
| total_tax_3 | float | Total amount of VAT according to 3rd VAT percentage over all invoice items. Calculated automatically and cannot be specified by yourself. | 0.00 |
| cash_discount_total | float | Total amount of the financial discount granted on the invoice total. Calculated automatically and cannot be specified yourself. | 1.20 |
| discount_total_with_tax | float | Total amount of the discount granted on the invoice total including VAT. Calculated automatically and cannot be specified yourself. | 12.10 |
| total_with_tax | float | Total amount over all invoice items including VAT. Calculated automatically and cannot be specified yourself. | 242.00 |
| total_costs | float | Total amount of all reminder costs. Calculated automatically and cannot be specified yourself. | 5.00 |
| total_paid | float | Total amount already paid by customer. Is the summons of all amounts in payments. Calculated automatically and cannot be specified yourself. | 25.00 |
| outstanding_balance | float | Additional remaining balance to be paid by the customer (regardless of the amount of the invoice). This field can only be specified via the API. Contact the helpdesk for more information about the use of this field. | 100.00 |
| structured_message | number | Structured communication according to Belgian bank format (without formatting) with a length of 12 digits and with a check on the checksum (last 2 digits). Optional to give. Not applicable for credit note (type = 'creditnote'). Automatically generated if not specified and if this option was activated in the Settings. | 278781035591 |
| automatic_reminders | text | If activated, automatic reminders are sent out for this invoice as long as the invoice does not have the status 'closed'. Can have a value of 'yes' or 'no'. Optional to give. If not specified, the default value is determined using the settings of the account. | yes |
| note | text | Note that is shown at the bottom of the invoice. Optional. Maximum 2000 characters long. | 25 € costs for late payments |
| note_html | html | Note that is shown at the bottom of the invoice in HTML format. Optional. Maximum 2000 characters long. | <p>25 € costs for late payments </p> |
| last_activity | datetime | Time with the last activity of the invoice. Cannot be specified, automatically determined by the system. | 2018-05-03 11:33:45 |
| tags | list | List of tags indicating which actions have already been performed for the invoice. | – |
| custom_values | list | List of standard fields that can be added to the invoice. The available standard fields can be set via “Settings” > “Advanced”. | – |
| payments | list | List of payments received from the invoice. | – |
| costs | list | List of invoice reminder costs. | – |
| remarks | list | List of personal notes on the invoice | – |
| events | list | List of invoice events. | – |
Subdomain : items ( < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| item_id | int | Unique ID of the invoice item. Generated by the system. Required to be specified in URL (except for creation). | 4004 |
| invoice_id | int | Unique ID of the invoice. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to invoice item. Generated by the system. To be used when addressing an invoice item via the API. | – |
| amount | float | Amount per unit (1 quantity) of the invoice item excluding VAT. Mandatory to be used if field tax_included='no'. Can be specified to 4 decimal places. The maximum amount is 9,999,999,9999. Will be calculated automatically if amount is specified via 'amount_with_tax'. | 100.00 |
| amount_with_tax | float | Amount per unit (1 quantity) of the invoice item including VAT. Mandatory to be used if field tax_included='yes'. Can be specified to 4 decimal places. The maximum amount is 9,999,999,9999. Will be calculated automatically if amount was entered via 'amount'. | 121.00 |
| quantity | float | Number of units of the invoice item. Can be specified to 2 decimal places. If not specified, '1' is used by default. The maximum amount is 999,999.99. | 2 |
| unit | text | Unit of the item. Not required. Maximum 10 characters long and must start with a letter. Must not contain spaces. | piece |
| stockitem_code | text | Item code linked to the item. Not required. Maximum 20 characters long. Adding an item code does not affect the number of items in stock on the item list. | A0000001 |
| stockitem_id | int | Unique ID of the article. Not required. Can only be used during creation or editing. By submitting this ID, the stock of the item will be automatically adjusted and fields that are not specified, such as “description”, “amount”, “stockitem_code”, “tax_rate”, “tax_rate_special_status” and “general_ledger_account” are automatically completed. | 2002 |
| quantity_with_unit | text | Quantity and unit of the item separated by a space. Can only be used during creation or editing. Cannot be used in combination with field 'quantity' or 'unit'. The same restrictions as 'quantity' and 'unit' fields apply. | 2 piece |
| description | text | Description of the invoice item. Mandatory to be specified when creating. | product description |
| description_html | html | Description of the invoice item in HTML format. Mandatory to be specified when creating. | <p>product description</p> |
| total_without_tax | float | Total amount of the invoice item excluding VAT. Is calculated by means of fields 'amount' and 'quantity'. | 200.00 |
| tax_rate | float | Tax percentage of the invoice item. Must match one of the VAT percentages of the invoice or must be '0'. If not specified, '0' is assumed. | 21 |
| tax_rate_special_status | text | Code deviating VAT rate from the used VAT percentage (tax_rate) of the invoice item. Can only be used if the VAT percentage is 0. The field is optional and can be up to 20 characters long. | MC |
| total_with_tax | float | Total amount of the invoice item including VAT. Is calculated using the fields 'amount', 'quantity' and 'tax_rate'. | 242.00 |
| general_ledger_account | text | Code of the ledger account linked to the invoice item. Not required. Between 6 and 8 characters long, only numbers are allowed. | 700000 |
| custom_values | list | List of standard fields. The available fields are addes via "Settings" > "Advanced". | – |
Subdomein : custom_values ( < invoices + items < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| name | text | Internal name of the default field. Determined when the default field is created and can be used as a unique identifier for the default field. Mandatory when adding or changing the value of this field. | myreference |
| description | text | Name or description of the default field as it appears when used. Returned for informational purposes only and cannot be modified via the API. | Our reference |
| value | text | Value of the default field. Maximum 75 characters long. | 123456 |
Subdomein : tags ( < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| tag_id | number | Unique ID of the tag | 3 |
| name | text | Tag name or code. Possible values: 'printed' (tag_id=3), 'sent' (tag_id=6), 'accountant' (tag_id=9). | printed |
Note: The 'tags' subdomain is not a full-fledged subdomain and cannot be accessed separately from the 'invoices' domain. It is not possible to adjust values in tags via the API. This data is automatically added based on actions performed.
Subdomain : payments ( < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| payment_id | int | Unique ID of the payment. Generated by the system. Required to be specified in URL (except for creation). | 5010 |
| invoice_id | int | Unique ID of the invoice. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to payment. Generated by the system. To be used when requesting payment via the API. | – |
| date | date | Date the payment was recorded. Has the format YYYY-MM-DD. If not specified at creation, current date is used. | 2012-02-15 |
| amount | float | Payment amount. Mandatory when creating an alternative field 'remaining_amount' can be specified. | 25.00 |
| method | text | Payment method of payment. Optional to give. Valid values: transfer, cash, debit card, credit card, direct collection, online, bancontact, ideal. | cash |
| description | text | Description of the payment. Optional to give. Maximum 255 characters long. | Deposit |
| remaining_amount | text | Only applicable when adding a payment (POST/PUT). This designation ensures that the 'amount' field contains the full remaining unpaid amount of the invoice. Not required field, if specified it always has value 'yes'. | yes |
Subdomain : costs ( < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| cost_id | int | Unique ID of the comment. Generated by the system. Required to be specified in URL (except for creation). | 5030 |
| invoice_id | int | Unique ID of the invoice. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to reminder cost. Generated by the system. To be used when requesting payment via the API. | – |
| amount | float | Amount of the reminder cost. Mandatory to include when creating. | 5.00 |
| description | text | Description of the reminder cost. Optionally to be included, if not included, “Remembrance cost” is used as standard. Maximum 30 characters long. | Reminder cost |
Subdomain : remarks ( < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| remark_id | int | Unique ID of the comment. Generated by the system. Required to be specified in URL (except for creation). | 5020 |
| invoice_id | int | Unique ID of the invoice. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to comment. Generated by the system. To be used when addressing comment via the API. | – |
| date | date | Date the comment was added. If not specified, the current date is used. Format is YYYY-MM-DD. | 2012-02-15 |
| description | text | Description of the comment. Mandatory to be specified when creating or modifying if description_html is not specified. | Customer has already received goods |
| description_html | html | Description of the comment in HTML format. Mandatory to be specified upon creation or modification if description is not provided. | <p>Customer has already received goods </p> |
Subdomain : events ( < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| event_id | int | Unique ID of the event. Generated by the system. Required to be specified in URL. | 5030 |
| invoice_id | int | Unique ID of the invoice. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to event. Generated by the system. To be used when calling event via the API. | – |
| date | date | Date when the event occurred. Format YYYY-MM-DD. | 2012-02-15 |
| type | text | Event type. Currently only 'email sent' possible. | email sent |
| content | text | Content or description of the event. With type 'email sent' the content of the email will be sent here. | Attached your invoice |
| recipients | list | List of event recipients. | – |
Note: An element of the 'events' subdomain cannot be modified or created by yourself. Only the system can create an 'event'.
Subdomain : recipients ( < events < invoices )
| Field name | Type | Description | Example |
|---|---|---|---|
| name | text | Name (first name + last name) of the recipient. | Bart Decouster |
| email_address | text | Email address of the recipient. | [email protected] |
| external_event_recipient_id | text | External unique reference to this record. | 17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6 |
| status | text | Status that returns whether the event has already arrived at the recipient. Possible statuses are: sending, sent, open, failed. | sending |
| information | text | Additional information about the status. An error message will appear here if status is set to 'failed'. | – |
Note: The 'recipients' subdomain is not a full-fledged subdomain and cannot be accessed separately from the 'events' subdomain.
Type : Address
| Field name | Type | Description | Example |
|---|---|---|---|
| street | text | Straat + house number of the address. Not required, maximum 150 characters long. | Langestraat 189 |
| street2 | text | Second address line of the address. Not required, maximum 150 characters long. | |
| city | text | City of the address. Not required, maximum 50 characters long. | Antwerp |
| postal_code | text | The postal code of the city of the address. Not required, maximum 10 characters long. | 2000 |
| country | text | Country of the cutomer. Cannot be specified. Is automatically determined by country_code. | Belgium |
| country_code | text | Customer country code. Mandatory, 2 characters long, in capital letters. | BE |
Example in XML of an invoice:
<invoice>
<invoice_id>3003</invoice_id>
<uri>https://eenvoudigfactureren.be/api/v1/invoices/3003</uri>
<external_invoice_id>Invoice-0983984</external_invoice_id>
<client_id>1001</client_id>
<client_uri>https://eenvoudigfactureren/api/v1/clients/1001</client_uri>
<client_name>IT Services BVBA</client_name>
<client_attention>Dienst administratie</client_attention>
<type>invoice</type>
<number>INV2012-001</number>
<layout_id>8001</layout_id>
<reference>ID123456789</reference>
<date>2012-02-15</date>
<date_delivery>2012-02-15</date_delivery>
<status>open</status>
<days_due>10</days_due>
<days_overdue>0</days_overdue>
<date_overdue>2012-02-25</date_overdue>
<billing_address>
<street>Olifantstraat 200</street>
<street2></street2>
<postal_code>9000</postal_code>
<city>Gent</city>
<country_code>BE</country_code>
<country>België</country>
</billing_address>
<delivery_address>
<street>Olifantstraat 200</street>
<street2></street2>
<postal_code>9000</postal_code>
<city>Gent</city>
<country_code>BE</country_code>
<country>België</country>
</delivery_address>
<site_address>
<street>Olifantstraat 200</street>
<street2></street2>
<postal_code>9000</postal_code>
<city>Gent</city>
<country_code>BE</country_code>
<country>België</country>
</site_address>
<discount_percentage>5</discount_percentage>
<cash_discount_percentage>2</cash_discount_percentage>
<cash_discount_days_valid>8</cash_discount_days_valid>
<cash_discount_date_valid>2012-02-23</cash_discount_date_valid>
<currency>EUR</currency>
<exchange_rate>1</exchange_rate>
<language>dutch</language>
<tax_calculation>total</tax_calculation>
<tax_included>no</tax_included>
<items>
<item>
<item_id>4004</item_id>
<uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/items/4004</uri>
<description>product omschrijving</description>
<description_html><![CDATA[<p>product omschrijving</p>]]></description_html>
<amount>100.00</amount>
<amount_with_tax>121.00</amount_with_tax>
<quantity>2</quantity>
<unit>stuk</unit>
<stockitem_code>A000001</stockitem_code>
<total_without_tax>200.00</total_without_tax>
<tax_rate>21</tax_rate>
<total_with_tax>242.00</total_with_tax>
<general_ledger_account>700000</general_ledger_account>
<custom_values>
<custom_value>
<name>ean</name>
<description>EAN</description>
<value>100000000000001</value>
</custom_value>
</custom_values>
</item>
</items>
<discount_total_without_tax>10.00</discount_total_without_tax>
<total_refundable_discount>0.00</total_refundable_discount>
<total_without_tax>190.00</total_without_tax>
<tax_rate_1>21</tax_rate_1>
<total_tax_1>42.00</total_tax_1>
<tax_rate_2>12</tax_rate_2>
<total_tax_2>0.00</total_tax_2>
<tax_rate_3>6</tax_rate_3>
<total_tax_3>0.00</total_tax_3>
<discount_total_with_tax>12.10</discount_total_with_tax>
<total_with_tax>229.90</total_with_tax>
<total_costs>5.00</total_costs>
<total_paid>25.0</total_paid>
<structured_message>278781035591</structured_message>
<automatic_reminders>yes</automatic_reminders>
<note>25 € kosten bij laattijdige betalingen.</note>
<note_html><![CDATA[<p>25 € kosten bij laattijdige betalingen.</p>]]></note_html>
<last_activity>2018-05-03 11:33:45</last_activity>
<custom_values>
<custom_value>
<name>myreference</name>
<description>Onze referentie</description>
<value>123456</value>
</custom_value>
</custom_values>
<tags>
<tag>
<tag_id>3</tag_id>
<name>printed</name>
</tag>
</tags>
<payments>
<payment>
<payment_id>5010</payment_id>
<uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/payments/5010</uri>
<date>2012-02-15</date>
<amount>25.00</amount>
<method>cash</method>
<description>Voorschot</description>
</payment>
</payments>
<costs>
<cost>
<cost_id>5030</cost_id>
<amount>5.00</amount>
<description>Herinneringskost</description>
</cost>
</costs>
<remarks>
<remark>
<remark_id>5020</remark_id>
<uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/remarks/5020</uri>
<date>2012-02-15</date>
<description>Klant heeft goederen reeds ontvangen</description>
<description_html><![CDATA[<p>Klant heeft goederen reeds ontvangen</p>]]></description_html>
</remark>
</remarks>
<events>
<event>
<event_id>5030</event_id>
<uri>https://eenvoudigfactureren.be/api/v1/invoices/3003/events/5030</uri>
<date>2012-02-16</date>
<type>email sent</type>
<content>In bijlage uw factuur</content>
<recipients>
<recipient>
<name>Bart Decouster</name>
<email_address>[email protected]</email_address>
<external_event_recipient_id>17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6</external_event_recipient_id>
<status>sending</status>
<information>-</information>
</recipient>
</recipients>
</event>
</events>
</invoice>