Items from the domain “subscriptions” represent a subscription. With a subscription you can create periodic invoices.
Structure URL’s:
/api/v1/subscriptions: Subscription data
/api/v1/subscriptions/3003: Subscription with ID 3003
/api/v1/subscriptions/3003/items: Items from subscription with ID 3003
/api/v1/subscriptions/3003/items/4005: Item with ID 4005 from subscription with ID 3003
/api/v1/subscriptions/3003/remarks: Comments of subscription with ID 3003
/api/v1/subscriptions/3003/remarks/5010: Note with ID 5010 of subscription with ID 3003
Domain : subscriptions
Field name | Type | Description | Example |
---|---|---|---|
subscription_id | int | Unique ID of the subscription. Generated by the system. Required to be specified in URL (except for creation). | 3003 |
uri | text | URL to subscription. Generated by the system. To be used when addressing subscription via the API. | – |
external_subscription_id | text | (Unique) ID of the subscription that can be set by a third party. Maximum 50 characters long. Uniqueness of the value is not enforced. | Subscription-0983984 |
client_id | int | Unique ID of the customer. Mandatory to be specified when creating. | 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. Is automatically copied from the customer data if not specified. | IT Services BVBA |
client_attention | text | Attn of the customer. Is automatically taken from the customer data if not specified. | Aministration Department |
type | text | Type of the document. Always contains the value 'subscription'. It is determined by the system Type of document. Always contains the value "subscription". It is determined by the system and cannot be provided by the system itself. | subscription |
number | text | Unique number of the subscription. Generated if not provided. Maximum 255 characters long. | SUB2018-001 |
layout_id | int | Unique ID of the layout. If not specified, the default layout is determined automatically. Can be empty if no layout has been set for the account. | 8001 |
reference | text | Self-specified reference of the generated invoice. Not required. Maximum 250 characters long. | ID123456789 |
status | text | Status of the subscription. Possible values: 'open', 'completed', 'disabled'. | open |
days_due | int | Payment term in number of days of the generated 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. | 10 |
days_due_end_of_month | text | Always drop the payment term of the generated invoice at the end of the month. Can have value 'yes' or 'no'. If not specified, the default will be adopted according to settings. Not applicable for credit note. | yes |
billing_address | Address | Customer billing address. Is automatically taken from the customer data if not specified. | – |
delivery_address | Address | Customer's shipping address. Is automatically taken from the customer data if not specified. | – |
site_address | Address | Customer site address. Is automatically taken from the customer data if not specified. | – |
discount_percentage | float | Discount percentage that applies to the generated invoice. Amount must be between 0 and 100. Numbers up to 2 digits after the decimal point are allowed. If not specified, this value is 0. | 5 |
cash_discount_percentage | float | Financial discount percentage that applies to the generated invoice. Amount must be between 0 and 100. Numbers up to 2 digits after the decimal point are allowed. If not specified, this value is 0. If greater than 0, the field 'cash_discount_days_valid' is required. | 2 |
cash_discount_days_valid | int | Number of days that the financial discount is valid. Amount must be between 0 and 100. Only integers are allowed. If not specified, this value is 0. This field can only be specified if the 'cash_discount_percentage' field has also been specified. | 8 |
currency | text | The currency in which the generated invoice is formatted. This value must be part of an exhaustive list of the supported currencies. The value is 3 characters long and always in capital letters. If not specified, EUR is used. | EUR |
exchange_rate | number | The conversion rate to convert the amounts on the generated invoice into EUR. | 1 |
show_tax_for_exchange_rate | text | Show the VAT converted to EURO on the generated invoice if another currency is used (as required by law). Can have value 'yes' or 'no'. If empty, the default value is 'yes'. | yes |
language | text | The language in which the generated invoice is formatted. This value can contain 'dutch', 'french', 'english' or 'german' but can also be empty. If empty (= default value), the default language (dutch) is used. | dutch |
tax_calculation | text | The VAT calculation method of the generated invoice. Possible values: 'total', 'item'. By default, 'total' is used. With calculation method 'total' the VAT is calculated on the total amount of the invoice, with calculation method 'item' the VAT is calculated per invoice line. Switching between the calculation method can cause rounding differences. If 'tax_included'='yes', only 'item' is a valid value. | total |
tax_included | text | Indicates whether or not the amounts of the generated invoice have been entered including VAT and are therefore printed including VAT. Can have value '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 | Totaal bedrag van de toegekende korting op het factuurtotaal zonder rekening te houden met BTW. Wordt automatisch berekend en kan niet zelf worden opgegeven. | 10.00 |
total_refundable_deposit | float | Total amount of the discount on the invoice total without taking into account VAT. Calculated automatically and cannot be specified by yourself. | 5.00 |
total_without_tax | float | Total amount across all invoice items without taking into account VAT. Any discounts (discount_total_without_tax) and refundable packaging (total_refundable_deposit) are already included in this total. Calculated automatically and cannot be specified by yourself. | 200.00 |
tax_rate_1 | float | 1st VAT percentage that can be used on the invoice. Taken from the settings during creation and cannot be specified by 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 by yourself. | 42.00 |
tax_rate_2 | float | 2nd VAT percentage that can be used on the invoice. Taken from the settings during creation and cannot be specified by 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 by 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 granted financial discount on the invoice total. Calculated automatically and cannot be specified by yourself. | 1.20 |
discount_total_with_tax | float | Total amount of the discount on the invoice total, including VAT. Calculated automatically and cannot be specified by yourself. | 12.10 |
total_with_tax | float | Total amount across all invoice items including VAT. Calculated automatically and cannot be specified by yourself. | 242.00 |
generate_structured_message | text | Generate structured communication when creating invoice. Can have value 'yes' or 'no'. If not specified, the default will be adopted according to settings. Not applicable for credit note. | no |
structured_message | number | Structured communication according to Belgian bank format (without formatting) with a length of 12 digits and with checksum check (last 2 digits). Optional to give. Cannot be specified if 'generate_structured_message' is active. Not applicable for credit note. | 278781035591 |
note | text | Note shown at the bottom of the generated invoice. Optional to give. Maximum 2000 characters long. | 25 € fee for late payments. |
note_html | html | Note shown at the bottom of the generated invoice in HTML format. Optional to give. Maximum 2000 characters long. | <p>25 € fee for late payments.</p> |
next_date | date | Next date on which an invoice is to be generated for the subscription. Format YYYY-MM-DD. If not specified, the date will be set tomorrow relative to the subscription creation date. Date is incremented each time an invoice is generated. | 2018-07-01 |
frequency | number | Frequency that together with 'interval' determines with which frequency an invoice is generated (for example “every 2 months”). Value must be between 1 and 999. If not given, 1 is set. | 2 |
interval | text | Interval that together with 'frequency' determines the frequency with which an invoice is generated (for example “every 2 months”). Allowed values: 'day', 'week', 'month', 'year'. Required to specify. | month |
times | number | Number of times an invoice for the subscription is yet to be generated. Optional to give. If specified, the value is reduced by 1 each time an invoice is generated. If value 0, the status of the subscription is automatically set to 'completed'. | 10 |
expiration_date | date | End date until which invoices for the subscription are to be generated. Optional to give. If 'next_date' is greater than 'expiration_date', the status of the subscription is automatically set to 'completed'. | 2030-12-31 |
direct_collection | text | Automatic payment via direct debit if available (via Mollie). Can have value 'yes' or 'no'. Default value is 'no' if not specified. | no |
auto_send_invoice | text | Automatically send by e-mail the generated invoice. Can have value 'yes' or 'no'. Default value is 'no' if not specified. | yes |
email_recipients | text | Recipients of the invoice automatically sent by e-mail. May contain customer contact_id or one of the following values: 'main_contact' (customer email address), 'first_contact' (customer email address or other available customer email address), 'all_contacts' (all email addresses of the customer) or 'myself' (account owner's email address in copy). It is also possible to provide a space separated list of previous values or in JSON format the data can be passed as an array. Mandatory if 'auto_send_invoice' has been activated. | first_contact |
email_subject | text | Subject of the email sent. Taken from the settings if not specified. | |
email_content | text | Content (body) of the sent e-mail. Taken from the settings if not specified. | |
email_filetype | text | File format of the invoice when sent by e-mail. Can contain value 'pdf', 'ubl' or 'both'. If not specified, 'pdf' is set. | |
last_activity | datetime | Time with the last activity of the subscription. Cannot be specified, determined automatically by the system. | 2018-05-03 11:33:45 |
custom_values | list | List of standard fields that can be added to the subscription. The available standard fields can be set via “Settings” > “Advanced”. | – |
remarks | list | List of personal notes on the subscription | – |
Subdomain : items ( < subscriptions )
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 99,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 | Article 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 | Article 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. | 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 at creation (alternatively, field description_html can be used). | product description |
description_html | html | Description of the invoice item in HTML format. Mandatory to be specified at creation (alternatively, field description can be used). | <p>product description</p> |
total_without_tax | float | Total amount of the invoice item excluding VAT. Is calculated using the 'amount' and 'quantity' fields. | 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 added via “Settings” > “Advanced”. | – |
Subdomain : custom_values ( < subscriptions + items < subscriptions )
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 |
Subdomain : remarks ( < subscriptions )
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 (alternatively, field description_html can be used). | Customer has already received goods |
description_html | html | Description of the comment in HTML format. Mandatory to be specified when creating or modifying (alternatively, field description can be used). | <p>Customer has already received goods</p> |
Example in XML of a subscription:
<subscription> <subscription_id>3003</subscription_id> <uri>https://eenvoudigfactureren.be/api/v1/subscriptions/3003</uri> <external_subscription_id>Invoice-0983984</external_subscription_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>subscription</type> <number>SUB2018-001</number> <layout_id>8001</layout_id> <reference>ID123456789</reference> <status>open</status> <days_due>10</days_due> <days_due_end_of_month>yes</days_due_end_of_month> <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/subscriptions/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_paid>25.0</total_paid> <generate_structured_message>no</generate_structured_message> <structured_message>278781035591</structured_message> <note>25 € kosten bij laattijdige betalingen.</note> <note_html><![CDATA[<p>25 € kosten bij laattijdige betalingen.</p>]]></note_html> <next_date>2018-07-01</next_date> <frequency>2</frequency> <interval>month</interval> <times>10</times> <expiration_date>2030-12-31</expiration_date> <direct_collection>no</direct_collection> <auto_send_invoice>yes</auto_send_invoice> <email_recipients>first_contact</email_recipients> <email_subject>Factuur %document-number%</email_subject> <email_content>In bijlage uw factuur</email_content> <email_filetype>pdf</email_filetype> <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> <remarks> <remark> <remark_id>5020</remark_id> <uri>https://eenvoudigfactureren.be/api/v1/subscriptions/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> </subscription>