OData (Open Data Protocol)

Is an ISO certified standard that is used in rest APIs to define filters.

Odata start guide or Odata References

📘

Pagination

Endpoints in the API that support OData such as documents, orders, parties and products have a default pagesize op 120 records. The responses will contain a NextpageLink as long as there are still records left to be fetched.

Alternatively the "&$skip={skipAmount}" filter can be used to manually go over different pages.

Quick guide

Apply a filter

To add filters the "$filter" query param must be added. The property on which the filter must be applied is added as plain text followed by +eq+ to signify that the filter must find a record where the property value is equal to the filter value. The filter value can be added between single or double quotes. Eg. filter on the parties DisplayName: /v1/parties$filter=DisplayName+eq+'Billit'.

Multiple filters can be applied at once by chaining them with "+and+", eg. filtering on OrderType and Direction: /v1/orders?$filter=OrderType+eq+'Invoice'+and+OrderDirection+eq+'Income'

Filters can be applied to subproperties by appending a /(slash) and the subproprty eg. filter on the subproperty DisplayName of the CounterParty of an order: /v1/orders?$filter=CounterParty/DisplayName+eq+'Billit'

Apply sorting

Sorting is applied via the "$orderby" param and simply adding the property the sorting needs to be applied on, eg. /v1/orders?$orderby=OrderNumber. The default sorting is ascending, this can be reversed by adding "desc".

Sorting on subproperties is also possible and the subproperty is defined in the same way as in a filter, property/subproperty.

Multiple properties can be defined to sort on, these are added separated by a comma, eg. order on OrderNumber and then on OrderDate: /v1/orders?$orderby=OrderNumber, OrderDate.

Combine multiple query options

Multiple types of query paramters can be combined by chaining them with the & (ampersand) eg. give a top 5 of the most recent income invoice for the customer Billit: $filter=CounterParty/DisplayName+eq+'Billit'+and+OrderType+eq+'Invoice'+and+OrderDirection+eq+'Income'

Limit your results

Limit the amount of items present in the result by using the $top={amount}. Note: this can not be used to exceed the default page size of 120 records.

Skip over rows

A page with result will contain a maximum of 120 records by default. You can retrieve records outside of the page by using the $skip={amout} query param. Alternatively you can use the url provided in the NextpageLink in the result, this will always have the correct amount to not fetch any records more than once.

Examples

Let's see with some examples what OData can do for you.

The following GET request will provide you with all changed invoices from the date provided, in this example: the first of January

GET /v1/orders?$filter=LastModified+ge+DateTime'2022-01-01'+and+OrderType+eq+'Invoice'&$orderby=LastModified+asc

You can use this on other GET endpoints too, here is an example on our Party Endpoint.

The following GET request will provide us with all customers that were Last Modified >= 1st of January 2019, sorted

GET /v1/parties?$filter=PartyType+eq+'Customer'+and+LastModified+ge+DateTime'2019-01-01'&$orderby=LastModified+asc

The following GET request will provide us with all products that were Last Modified >= 1st of January 2019, sorted

GET /v1/products?$filter=LastModified+ge+DateTime'2019-01-01'+and+GroupName+eq+'Testgroep'&$orderby=LastModified+asc

The following GET request will provide us with all the orders, with an order date between 2022-01-01 and 2022-12-31

GET /v1/orders?$filter=OrderDate ge datetime'2022-01-01' and OrderDate le datetime'2022-12-31'

The following GET request will provide us with all the orders, Using the ExternalProviderID and only returning those

Use case: Using a POST, you stored the Unique Invoice ID from your software in Billit using the ExternalProviderID. Now you want to check if any invoices exists with that unique
ExternalProviderID . You can use the following filter.

GET /v1/orders?$filter=ExternalProviderID+eq+'MyCustomNumber'