Items from the “orders” domain represent an order form..
Structure URLs:
https://api.simplybooks.be/api/v1/orders: Order form details
https://api.simplybooks.be/api/v1/orders/4004: Order form with ID 4004
https://api.simplybooks.be/api/v1/orders/4004/items: Items from order form with ID 4004
https://api.simplybooks.be/api/v1/orders/4004/items/5004: Item with ID 5004 from order form with ID 4004
https://api.simplybooks.be/api/v1/orders/4004/remarks: Remarks of order form with ID 4004
https://api.simplybooks.be/api/v1/orders/4004/remarks/5010: Note with ID 5010 of order form with ID 4004
https://api.simplybooks.be/api/v1/orders/4004/events: Events of order form with ID 4004
https://api.simplybooks.be/api/v1/orders/4004/events/5030: Event with ID 5030 of order form with ID 4004
Domain : orders
| Field name | Type | Description | Example |
|---|---|---|---|
| order_id | int | Unique ID of the order form. Generated by the system. Required to be specified in URL (except for creation). | 4004 |
| uri | text | URL to the order form. Generated by the system. To be used when addressing the order form via the API. | – |
| external_order_id | text | (Unique) ID of the order form that can be set by a third party. Maximum 50 characters long. Uniqueness of the value is not enforced. | Order-548984 |
| client_id | int | Unique ID of the customer. Required to specify. | 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 taken 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. | Administration Department |
| type | text | Type of the document. Always contains the value: 'order'. It is determined by the system and cannot be passed on by itself. | order |
| number | text | Unique number of the order form as shown on the order form. Generated if not provided. Maximum 255 characters long. | 00000001 |
| 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 order form. Not required. Maximum 250 characters long. | REF123456789 |
| date | date | Date of creation of the order form. Generated if not provided. Format YYYY-MM-DD. | 2018-02-15 |
| days_delivery | int | Number of days of delivery after the date of the order. If not specified, the defaults are taken according to settings. Maximum value 999 days. If 0 there is no delivery date. | 14 |
| date_delivery | date | Date of delivery of the order form. Generated from 'date' and 'days_delivery'. Format YYYY-MM-DD. | 2018-02-29 |
| days_late | int | Number of days that the delivery date has already been exceeded compared to the current date. Only shown if status is 'late'. Generated by the system and cannot be specified by yourself. | 0 |
| deposit_paid | float | Advance amount of the order form. Can be specified to 2 decimal places. If not specified, 0.00 is used by default. | 10.00 |
| status | text | Status of the order form. Possible values: 'open', 'late', 'create_invoice', 'completed'. Status 'late' is automatically determined by the system and cannot be specified by yourself. The values 'open' (=Outstanding), 'create_invoice' (=To be invoiced), 'completed' (=Completed) can be specified. Default status is 'open'. | open |
| 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 entire order form. 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 |
| currency | text | The currency in which the order form is issued. 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 order form into EUR. | 1 |
| show_tax_for_exchange_rate | text | Show the VAT converted to EURO on the order form if another currency is used (legally required on an invoice). Can have value 'yes' or 'no'. If empty, the default value is 'yes'. | yes |
| language | text | The language in which the order form is drawn up. 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 order form. Possible values: 'total', 'item'. By default, 'total' is used. With the calculation method 'total' the VAT is calculated on the total amount of the order form, with the calculation method 'item' the VAT is calculated per order form 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 on the order form are stated 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 order form items. | – |
| discount_total_without_tax | float | Total amount of the discount granted on the total order form without taking into account VAT. Calculated automatically and cannot be specified by 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 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 order form. 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 across all items. Calculated automatically and cannot be specified by yourself. | 42.00 |
| tax_rate_2 | float | 2nd VAT percentage that can be used on the order form. 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 items. Calculated automatically and cannot be specified by yourself. | 0.00 |
| tax_rate_3 | float | 3rd VAT percentage that can be used on the order form. 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 items. Calculated automatically and cannot be specified by yourself. | 0.00 |
| discount_total_with_tax | float | Total amount of the discount granted on the total of the order form, including VAT. Calculated automatically and cannot be specified by yourself. | 12.10 |
| total_with_tax | float | Total amount across all items including VAT. Calculated automatically and cannot be specified by yourself. | 242.00 |
| note | text | Note shown at the bottom of the order form. Optional to give. Maximum 2000 characters long. | Warranty conditions applicable |
| note_html | html | Note shown at the bottom of the order form in HTML format. Optional to give. Maximum 2000 characters long. | <p>Warranty conditions applicable</p> |
| last_activity | datetime | Time with the last activity of the order form. Cannot be specified, automatically determined by the system. | 2018-05-03 11:33:45 |
| custom_values | list | List of standard fields that can be added to the order form. The available standard fields can be set via “Settings” > “Advanced”. | – |
| tags | list | List of tags indicating which actions have already been performed for the order form. | – |
| remarks | list | List of personal comments on the order form. | – |
| events | list | List of events from the order form. | – |
Subdomain : items ( < orders )
| Field name | Type | Description | Example |
|---|---|---|---|
| item_id | int | Unique ID of the purchase order item. Generated by the system. Required to be specified in URL (except for creation). | 4004 |
| order_id | int | Unique ID of the order form. Generated by the system. Required to be specified in URL. | 3003 |
| uri | text | URL to order form item. Generated by the system. To be used when addressing an order form item via the API. | – |
| amount | float | Amount per unit (1 quantity) of the purchase order 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 purchase order 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 purchase order 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. | stuk |
| 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. Passing this ID automatically completes fields that are not specified, such as “description”, “amount”, “stockitem_code”, “tax_rate”, “tax_rate_special_status” and “general_ledger_account”. | 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 stuk |
| description | text | Description of the order form item. Mandatory to be specified when creating. | product description |
| description_html | html | Description of the order form 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 purchase order item excluding VAT. Is calculated by means of fields 'amount' and 'quantity'. | 200.00 |
| tax_rate | float | VAT percentage of the purchase order item. Must match one of the VAT percentages of the order form or must be '0'. If not specified, '0' is assumed. | 21 |
| tax_rate_special_status | text | Code deviating VAT rate from the VAT percentage used (tax_rate) of the purchase order 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 order form item including VAT. Is calculated using the fields 'amount', 'quantity' and 'tax_rate'. | 242.00 |
| general_ledger_account | text | Ledger account code associated with the purchase order 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 ( < orders + items < orders )
| 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 : tags ( < orders )
| 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 subdomain 'tags' is not a full subdomain and cannot be addressed separately from domain 'orders'. It is not possible to adjust values in tags via the API. This data is automatically added based on actions performed.
Subdomain : remarks ( < orders )
| 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 |
| order_id | int | Unique ID of the order form. 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 insists on prompt delivery |
| 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 insists on prompt delivery</p> |
Subdomein : events ( < orders )
| Field name | Type | Description | Example |
|---|---|---|---|
| event_id | int | Unique ID of the event. Generated by the system. Required to be specified in URL. | 5030 |
| order_id | int | Unique ID of the order form. 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. | In bijlage uw bestelbon |
| 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 < orders )
| 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. | bart.decouster@hisdomain.com |
| 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 cannot be accessed separately from the 'events' subdomain.
Type : Address
| Field name | Type | Description | Example |
|---|---|---|---|
| street | text | Street + 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 customer. 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 order form:
<order>
<order_id>5005</order_id>
<uri>https://eenvoudigfactureren.be/api/v1/orders/5005</uri>
<external_order_id>Order-0983984</external_order_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>order</type>
<number>00000001</number>
<layout_id>8001</layout_id>
<reference>ID123456789</reference>
<date>2018-02-15</date>
<days_delivery>14</days_delivery>
<date_delivery>2018-02-29</date_delivery>
<days_late>28</days_late>
<deposit_paid>10.00</deposit_paid>
<status>open</status>
<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>
<currency>EUR</currency>
<exchange_rate>1</exchange_rate>
<show_tax_for_exchange_rate>yes</show_tax_for_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/orders/5005/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_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>
<note>Garantievoorwaarden zijn van toepassing.</note>
<note_html><![CDATA[<p>Garantievoorwaarden zijn van toepassing.</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>
<remarks>
<remark>
<remark_id>5020</remark_id>
<uri>https://eenvoudigfactureren.be/api/v1/orders/5005/remarks/5020</uri>
<date>2012-02-15</date>
<description>Klant dringt aan op spoedige levering</description>
<description_html><![CDATA[<p>Klant dringt aan op spoedige levering</p>]]></description_html>
</remark>
</remarks>
<events>
<event>
<event_id>5030</event_id>
<uri>https://eenvoudigfactureren.be/api/v1/orders/5005/events/5030</uri>
<date>2012-02-16</date>
<type>email sent</type>
<content>In bijlage uw bestelbon</content>
<recipients>
<recipient>
<name>Bart Decouster</name>
<email_address>bart.decouster@hisdomain.com</email_address>
<external_event_recipient_id>17ad5dfc-b03e-4fd3-b66b-05b264cfa0c6</external_event_recipient_id>
<status>sending</status>
<information>-</information>
</recipient>
</recipients>
</event>
</events>
</order> More info about the API? Read the useful articles below