Order search

This tutorial explains to you how to search for orders using the route GET /rest/orders/search.

The route /rest/orders/search can be called with the filters given in the request body, as will be shown in this tutorial. Since for some clients it is not possible to send request data in the body when using GET, the route can also be called with POST.

The filters can be given either as query string parameters ("simple filters") or in the request body ("complex filters"). Sending the filters in the request body is more complex but offers you more possibilities to narrow down search results and to combine filters.

To see which filters are available, refer to the REST documentation.

Search results

For example, the result of a search can look like this:

{
    "page": 1,
    "totalsCount": 2,
    "isLastPage": true,
    "lastPageNumber": 1,
    "firstOnPage": 1,
    "lastOnPage": 2,
    "itemsPerPage": 50,
    "entries": [
        {
            "id": 16578,
            "referrerId": 0,
            "roundTotalsOnly": true,
            "numberOfDecimals": 4,
            "plentyId": 123,
            "typeId": 3,
            "lockStatus": "unlocked",
            "locationId": "1",
            "createdAt": "2021-12-22T14:43:55+01:00",
            "updatedAt": "2021-12-22T14:45:03+01:00",
            "statusId": 9,
            "ownerId": "3"
        },
        {
            "id": 16577,
            "referrerId": 0,
            "roundTotalsOnly": true,
            "numberOfDecimals": 4,
            "plentyId": 123,
            "typeId": 1,
            "lockStatus": "unlocked",
            "locationId": "1",
            "createdAt": "2021-12-22T14:40:19+01:00",
            "updatedAt": "2021-12-22T14:42:02+01:00",
            "statusId": 7,
            "ownerId": "3"
        }
    ]
}

The orders are lazy loaded per default. This means that no relations are loaded. To have the default relations loaded, the parameter lazyLoaded can be set to true. By using the paramter with, the required relations can also be defined manually.

Simple filters

When searching by using the simple filters, the filters are given as query string parameters. The shown operators are available only for filters for which they are applicable. For example, it is not possible to filter for a range of a string filter.

Searching for single values

To search for single values, the filters can simply be defined like this:

GET /rest/orders/search?orderTypeId=1&statusId=3

This filters all sales orders (orderTypeId = 1) that are in status 3.

This notation is equivalent to the example above:

GET /rest/orders/search?orderTypeId=eq:1&statusId=eq:3

Searching for multiple values

This is an example how to filter all orders that are in status 3 or 4:

GET /rest/orders/search?statusId=in:3,4

Searching for ranges

To filter for a range of values, these operators are availabe:

  • lt: less than

  • lte: less than equal

  • gt: greater than

  • gte: greater than equal

  • between: values between the given values, bounds are inclusive

This is an example how to filter all orders in a status less than 7:

GET /rest/orders/search?statusId=lt:7

And this example filters all orders that were created between the dates 2021-12-22T00:00:00+01:00 and 2021-12-22T23:59:59+01:00:

GET /rest/orders/search?createdAt=between:2021-12-22T00%3A00%3A00%2B01%3A00,2021-12-22T23%3A59%3A59%2B01%3A00

Data given as query string parameters have to be URL encoded. So in this example the string 2021-12-22T00:00:00+01:00 must be encoded as 2021-12-22T00%3A00%3A00%2B01%3A00. This is not necessary when sending the filters in the request body.

Search with logical operators

To filter for example all orders that are not in the status 3, use the not operator:

GET /rest/orders/search?statusId=not:3

It is possible to combine filters for the same field with logical AND or OR operators.

Filter all orders that are in a status greater 3 and less than 5:

GET /rest/orders/search?statusId=gt:3+AND+lt:5

Filter all orders that are in status 3 or a status greater than 6:

GET /rest/orders/search?statusId=eq:3+OR+gt:6

Complex filters

Complex filters are given in the request body in the JSON format. This is an example of how to filter all orders that are in status 3:

GET /rest/orders/search
{
    "conditionType": "and",
    "fields": [
        {
            "field": "statusId",
            "operator": "eq",
            "value": 3
        }
    ],
    "groups": []
}

The complex filters are defined as a "group" whereby each group can contain other groups. A group consist of these fields:

  • conditionType: The logical operator that defines how the values in fields and groups should be combined. Possible values are and and or.

  • fields: An array of the filters.

  • groups: An array of nested groups.

Each value of the fields array consists of these fields:

  • field: The name of the order filter as defined in the REST documentation.

  • operator: Defines how to filter.

  • value: The value to filter for. Can be a single value, an array or null (depending on the operator).

These are the possible operators:

  • eq: The value must be equal to the given value.

  • not: The value must not be equal the given value.

  • in: The value must be present in the given array.

  • nin: The value must not be present in the given array.

  • null: The value must not exist.

  • nn: The value must exist.

  • lt: The value must be less than the given value.

  • lte: The value must be less than equal the given value.

  • gt: The value must be greater than the given value.

  • gte: The value must be greater than equal the given value.

  • between: The value must be between the two given values.

Combining filters

This example filters all orders that are sales orders and that are in a status between 3 and 5. Both filters must apply because conditionType = and.

GET /rest/orders/search
{
    "conditionType": "and",
    "fields": [
        {
            "field": "orderTypeId",
            "operator": "eq",
            "value": 1
        },
        {
            "field": "statusId",
            "operator": "between",
            "value": [3, 5]
        }
    ],
    "groups": []
}

The following example filters all orders where there is an order item present with either variation ID = 1001 or item ID = 107. Only one of the filters has to apply because conditionType = or.

GET /rest/orders/search
{
    "conditionType": "or",
    "fields": [
        {
            "field": "itemVariationId",
            "operator": "eq",
            "value": 1001
        },
        {
            "field": "itemId",
            "operator": "eq",
            "value": 107
        }
    ],
    "groups": []
}

Nested filters

For more complex conditions, the field groups can be used. The given groups are combined as defined in the conditionType of the parent group. Inside the given groups another conditionType can be used.

This example filters all orders that are sales orders, have the referrer ID 9 and are in either a status less than equal 5 or equal 8.

GET /rest/orders/search
{
    "conditionType": "and",
    "fields": [
        {
            "field": "orderTypeId",
            "operator": "eq",
            "value": 1
        },
        {
            "field": "referrerId",
            "operator": "eq",
            "value": 9
        }
    ],
    "groups": [
        {
            "conditionType": "or",
            "fields": [
                {
                    "field": "statusId",
                    "operator": "lte",
                    "value": 5
                },
                {
                    "field": "statusId",
                    "operator": "eq",
                    "value": 8
                }
            ],
            "groups": []
        }
    ]
}

Special filter names

Some filters like the ones for properties and dates use a name that is exchangeable. This way, the property or date to be filter for can be specified.

This example filters for orders where the order property with type ID 2 (shipping profile) equals the value 7:

GET /rest/orders/search
{
    "conditionType": "and",
    "fields": [
        {
            "field": "orderProperty_2",
            "operator": "eq",
            "value": 7
        }
    ],
    "groups": []
}

The contact ID can be filtered like this:

GET /rest/orders/search
{
    "conditionType": "and",
    "fields": [
        {
            "field": "relationReference_contact_receiver",
            "operator": "eq",
            "value": 105
        }
    ],
    "groups": []
}

Here the values "contact" and "receiver" are exchangeable. When for example using "warehouse" and "sender", the warehouse is filtered.

Sorting

Sorting is done by setting the query string parameters sortBy and sortOrder. Per default, the results are sorted by order ID in descending order. This example shows how to sort by order ID in ascending order:

GET /rest/orders/search?sortBy=orderId&sortOrder=asc

The possible values for sortBy are defined in the REST documentation. For sortOrder the values asc (ascending) and desc (descending) are valid.