Powered By GitBook
Filtering data
How to add filters to your requests
When you fetch a collection of resources, you can add filters to further refine the results, using the filter[q] query parameter.
Filters can be combined according to an "AND" logic to send requests that fetch collections of resources meeting all the criteria within a set of multiple filters (see example).
Each single filter query is built like this:
1
filter[q][{{predicate}}]={{value}}
Copied!
Here, value stands for the value that the fetched resources have to match, while the predicateparameter has this format:
1
{{attributes}}_{{matcher}}
Copied!
Where attributes is a set of one or more attributes and matcher represents the condition to be met by the query.
Attributes can be combined according to an "OR" logic and can belong to either the fetched resource or to one of its relationships (see example).

List of Predicates

You can find here below the complete list of all possible predicates:
Predicate
Description
Example
*_eq
The attribute is equal to the filter value
filter[q][name_eq]=red+handbag
*_not_eq
The attribute is not equal to the filter value
filter[q][status_not_eq]=prospect
*_matches
The attribute matches the filter value with "LIKE" operator
filter[q][email_matches]=%@gmail.com
*_does_not_match
The attribute does not match the filter value with "LIKE" operator
filter[q][email_does_not_match]=%@hotmail.com
*_matches_any
The attribute matches all of the filter values (comma-separated) with "LIKE" operator
filter[q][email_matches_any]=%@gmail.com,%@hotmail.com
*_matches_all
The attribute matches all of the filter values (comma-separated) with "LIKE" operator
filter[q][name_matches_all]=%Pink%,%Logo%
*_does_not_match_any
The attribute does not match any of the filter values (comma-separated) with "LIKE" operator
filter[q][email_does_not_match_any]=%Pink%,%Logo%
*_does_not_match_all
The attribute matches none of the filter values (comma-separated) with "LIKE" operator
filter[q][email_does_not_match_all]=%@gmail.com,%@hotmail.com
*_lt
The attribute is less than the filter value
filter[q][amount_cents_lt]=2000
*_lteq
The attribute is less than or equal to the filter value
filter[q][amount_cents_lteq]=2000
*_gt
The attribute is greater than the filter value
filter[q][created_at_gt]=2019-01-01T01:00:00.000Z
*_gteq
The attribute is greater than or equal to the filter value
filter[q][updated_at_gteq]=2019-01-02T10:30:00.000Z
*_present
The attribute is not null and not empty
filter[q][description_present]=false
*_blank
The attribute is null or empty
filter[q][description_blank]=true
*_null
The attribute is null
filter[q][reference_null]=true
*_not_null
The attribute is not null
filter[q][reference_not_null]=false
*_in
The attribute matches any of the filter values (comma-separated)
filter[q][status_in]=placed,pending
*_not_in
The attribute matches none of the filter values (comma-separated)
filter[q][status_not_in]=approved,cancelled
*_lt_any
The attribute is less than any of the filter values (comma-separated)
filter[q][amount_cents_lt_any]=1500,700,3400
*_lteq_any
The attribute is less than or equal to any of the filter values (comma-separated)
filter[q][amount_cents_lteq_any]=1500,700,3400
*_gt_any
The attribute is greater than any of the filter values (comma-separated)
filter[q][amount_cents_gt_any]=1500,700,3400
*_gteq_any
The attribute is greater than or qual to any of the filter values (comma-separated)
filter[q][amount_cents_gteq_any]=1500,700,3400
*_lt_all
The attribute is less than all of the filter values (comma-separated)
filter[q][amount_cents_lt_all]=1500,700,3400
*_lteq_all
The attribute is less than or equal to all of the filter values (comma-separated)
filter[q][amount_cents_lteq_all]=1500,700,3400
*_gt_all
The attribute is greater than all of the filter values (comma-separated)
filter[q][amount_cents_gt_all]=1500,700,3400
*_gteq_all
The attribute is greater or equal to all of the filter values (comma-separated)
filter[q][amount_cents_gteq_all]=1500,700,3400
*_not_eq_all
The attribute is equal to none of the filter values (comma-separated)
filter[q][amount_cents_not_eq_all]=1000,2000,3000
*_start
The attribute starts with the filter value (comma-separated)
filter[q][email_start]=patrick
*_not_start
The attribute does not start with the filter value (comma-separated)
filter[q][email_not_start]=mary
*_start_any
The attribute starts with any of the filter values (comma-separated)
filter[q][email_start_any]=patrick,mary
*_start_all
The attribute starts with all of the filter values (comma-separated)
filter[q][email_start_all]=patrick,pat
*_not_start_any
The attribute does not start with any of the filter values (comma-separated)
filter[q][email_not_start_any]=patrick,pat
*_not_start_all
The attribute starts with none of the filter values (comma-separated)
filter[q][email_not_start_all]=patrick,mary
*_end
The attribute ends with the filter value
filter[q][email_end]=.com
*_not_end
The attribute does not end with the filter value
filter[q][email_not_end]=.it
*_end_any
The attribute ends with any of the filter values (comma-separated)
filter[q][email_end_any]=.com,.it
*_end_all
The attribute ends with all of the filter values (comma-separated)
filter[q][email_end_all]=.com,gmail.com
*_not_end_any
The attribute does not end with any of the filter values (comma-separated)
filter[q][email_not_end_any]=.com,gmail.com
*_not_end_all
The attribute ends with none of the filter values (comma-separated)
filter[q][email_not_end_all]=.com,.it
*_cont
The attribute contains the filter value
filter[q][name_cont]=unisex
*_not_cont
The attribute does not contains the filter value
filter[q][name_not_cont]=black
*_cont_any
The attribute contains any of the filter values (comma-separated)
filter[q][name_cont_any]=black,white
*_cont_all
The attribute contains all of the filter values (comma-separated)
filter[q][name_cont_all]=black,sleeve
*_not_cont_all
The attribute contains none of the filter values (comma-separated)
filter[q][sku_code_not_cont_all]=TSHIRT,SXXX
*_true
The attribute is true
filter[q][tax_included_true]=true
*_false
The attribute is false
filter[q][tax_included_false]=true
In case of comma-separated sets of values (e.g. *_in, *_matches_all, *_start_any etc.), pay attention to avoid whitespaces before or after each comma.

Examples

Combining filters

Request
Response
The following request fetches a collection of SKUs that have been created within a specific time range:
1
curl -X GET \
2
https://yourdomain.commercelayer.io/api/skus?filter[q][created_at_gt]=2018-01-01&filter[q][created_at_lt]=2018-01-31 \
3
-H 'Accept: application/vnd.api+json' \
4
-H 'Authorization: Bearer your-access-token'
Copied!
On success, the API responds with a 200 OK status code, returning a paginated collection of the resource objects that match the filter query:
1
{
2
"data": [
3
{
4
"id": "xYZkjABcde",
5
"type": "skus",
6
"links": {...},
7
"attributes": {
8
"code": "TSHIRTMM000000FFFFFFXLXX",
9
"name": "Black Men T-shirt with White Logo (XL)",
10
"description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
11
"image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
12
"tag_names": "Men, Black, XL",
13
"pieces_per_pack": 6,
14
"weight": 300.0,
15
"unit_of_weight": "gr",
16
"created_at": "2018-01-01T12:00:00.000Z",
17
"updated_at": "2018-01-01T12:00:00.000Z",
18
"reference": "ANYREFEFERNCE",
19
"metadata": {
20
"foo": "bar"
21
}
22
},
23
"relationships": {
24
"shipping_category": {
25
"links": {...}
26
},
27
"prices": {
28
"links": {...}
29
},
30
"stock_items": {
31
"links": {...}
32
},
33
"delivery_lead_times": {
34
"links": {...}
35
},
36
"sku_options": {
37
"links": {...}
38
}
39
},
40
"meta": {
41
"mode": "test"
42
}
43
},
44
{
45
"other": "... 9 skus (first page)"
46
}
47
],
48
"meta": {
49
"record_count": 50,
50
"page_count": 5
51
},
52
"links": {
53
"first": "https://yourdomain.commercelayer.io/api/skus?filter[q][created_at_gt]=2018-01-01&filter[q][created_at_lt]=2018-01-31&page[number]=1&page[size]=10",
54
"next": "https://yourdomain.commercelayer.io/api/skus?filter[q][created_at_gt]=2018-01-01&filter[q][created_at_lt]=2018-01-31&page[number]=2&page[size]=10",
55
"last": "https://yourdomain.commercelayer.io/api/skus?filter[q][created_at_gt]=2018-01-01&filter[q][created_at_lt]=2018-01-31&page[number]=5&page[size]=10"
56
}
57
}
Copied!

Combining filters and attributes

Request
Response
The following request fetches a collection of orders that have been created or updated after a specific date and that haven't been paid yet:
1
curl -X GET \
2
https://yourdomain.commercelayer.io/api/orders?filter[q][created_at_or_updated_at_gt]=2018-01-01&filter[q][payment_status_eq]=unpaid \
3
-H 'Accept: application/vnd.api+json' \
4
-H 'Authorization: Bearer your-access-token'
Copied!
On success, the API responds with a 200 OK status code, returning a paginated collection of the resource objects that match the filter query:
1
{
2
"data": [
3
{
4
"id": "xYZkjABcde",
5
"type": "orders",
6
"links": {...},
7
"attributes": {
8
"status": "pending",
9
"payment_status": "unpaid",
10
"fulfillment_status": "unfulfilled",
11
"guest": true,
12
"editable": true,
13
"placeable": false,
14
"customer_email": "[email protected]",
15
"language_code": "en",
16
"currency_code": "EUR",
17
"tax_included": true,
18
"tax_rate": null,
19
"freight_taxable": null,
20
"country_code": null,
21
"shipping_country_code_lock": null,
22
"coupon_code": null,
23
"subtotal_amount_cents": 4400,
24
"subtotal_amount_float": 44.0,
25
"formatted_subtotal_amount": "€44,00",
26
"shipping_amount_cents": 0,
27
"shipping_amount_float": 0,
28
"formatted_shipping_amount": "€0,00",
29
"payment_method_amount_cents": 0,
30
"payment_method_amount_float": 0,
31
"formatted_payment_method_amount": "€0,00",
32
"discount_amount_cents": 0,
33
"discount_amount_float": 0,
34
"formatted_discount_amount": "€0,00",
35
"total_tax_amount_cents": 0,
36
"total_tax_amount_float": 0,
37
"formatted_total_tax_amount": "€0,00",
38
"subtotal_tax_amount_cents": 0,
39
"subtotal_tax_amount_float": 0,
40
"formatted_subtotal_tax_amount": "€0,00",
41
"shipping_tax_amount_cents": 0,
42
"shipping_tax_amount_float": 0,
43
"formatted_shipping_tax_amount": "€0,00",
44
"payment_method_tax_amount_cents": 0,
45
"payment_method_tax_amount_float": 0,
46
"formatted_payment_method_tax_amount": "€0,00",
47
"discount_tax_amount_cents": 0,
48
"discount_tax_amount_float": 0,
49
"formatted_discount_tax_amount": "€0,00",
50
"total_amount_cents": 4400,
51
"total_amount_float": 44.0,
52
"formatted_total_amount": "€44,00",
53
"total_taxable_amount_cents": 4400,
54
"total_taxable_amount_float": 44.0,
55
"formatted_total_taxable_amount": "€44,00",
56
"subtotal_taxable_amount_cents": 4400,
57
"subtotal_taxable_amount_float": 44.0,
58
"formatted_subtotal_taxable_amount": "€44,00",
59
"shipping_taxable_amount_cents": 0,
60
"shipping_taxable_amount_float": 0,
61
"formatted_shipping_taxable_amount": "€0,00",
62
"payment_method_taxable_amount_cents": 0,
63
"payment_method_taxable_amount_float": 0,
64
"formatted_payment_method_taxable_amount": "€0,00",
65
"discount_taxable_amount_cents": 0,
66
"discount_taxable_amount_float": 0,
67
"formatted_discount_taxable_amount": "€0,00",
68
"total_amount_with_taxes_cents": 4400,
69
"total_amount_with_taxes_float": 44.0,
70
"formatted_total_amount_with_taxes": "€44,00",
71
"fees_amount_cents": 0,
72
"fees_amount_float": 0,
73
"formatted_fees_amount": "€0,00",
74
"skus_count": 2,
75
"line_item_options_count": 0,
76
"shipments_count": 0,
77
"payment_source_details": null,
78
"token": "order-token",
79
"cart_url": null,
80
"return_url": null,
81
"terms_url": null,
82
"privacy_url": null,
83
"checkout_url": "https://yourdomain.commercelayer.io/checkout/order-token",
84
"placed_at": null,
85
"approved_at": null,
86
"cancelled_at": null,
87
"payment_updated_at": null,
88
"fulfillment_updated_at": null,
89
"created_at": "2018-01-01T12:00:00.000Z",
90
"updated_at": "2018-01-01T12:00:00.000Z",
91
"reference": null,
92
"metadata": {}
93
},
94
"relationships": {
95
"market": {
96
"links": {...}
97
},
98
"customer": {
99
"links": {...}
100
},
101
"shipping_address": {
102
"links": {...}
103
},
104
"billing_address": {
105
"links": {...}
106
},
107
"available_payment_methods": {
108
"links": {...}
109
},
110
"payment_method": {
111
"links": {...}
112
},
113
"payment_source": {
114
"links": {...}
115
},
116
"line_items": {
117
"links": {...}
118
},
119
"shipments": {
120
"links": {...}
121
}
122
},
123
"meta": {
124
"mode": "test"
125
}
126
},
127
{
128
"other": "... 9 orders (first page)"
129
}
130
],
131
"meta": {
132
"record_count": 10,
133
"page_count": 1
134
},
135
"links": {
136
"first": "https://yourdomain.commercelayer.io/api/orders?filter[q][created_at_or_updated_at_gt]=2018-01-01&filter[q][payment_status_eq]=unpaid&page[number]=1&page[size]=10",
137
"last": "https://yourdomain.commercelayer.io/api/orders?filter[q][created_at_or_updated_at_gt]=2018-01-01&filter[q][payment_status_eq]=unpaid&page[number]=1&page[size]=10"
138
}
139
}
Copied!

Using filters that belong to a resource relationship

Request
Response
The following request fetches a collection of SKUs whose name, code or shipping category name starts with the string "TSHIRT" (as mentioned above, the attributeshipping_category_name here belongs to a relationship and filters the list of SKUs by the name of the associated shipping category):
1
curl -X GET \
2
https://yourdomain.commercelayer.io/api/skus?filter[q][name_or_code_or_shipping_category_name_start]=TSHIRT \
3
-H 'Accept: application/vnd.api+json' \
4
-H 'Authorization: Bearer your-access-token'
Copied!
On success, the API responds with a 200 OK status code, returning a paginated collection of the resource objects that match the filter query:
1
{
2
"data": [
3
{
4
"id": "xYZkjABcde",
5
"type": "skus",
6
"links": {...},
7
"attributes": {
8
"code": "TSHIRTMM000000FFFFFFXLXX",
9
"name": "Black Men T-shirt with White Logo (XL)",
10
"description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
11
"image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
12
"tag_names": "Men, Black, XL",
13
"pieces_per_pack": 6,
14
"weight": 300.0,
15
"unit_of_weight": "gr",
16
"hs_tariff_number": null,
17
"do_not_ship": false,
18
"do_not_track": false,
19
"created_at": "2018-01-01T12:00:00.000Z",
20
"updated_at": "2018-01-01T12:00:00.000Z",
21
"reference": "ANYREFEFERNCE",
22
"metadata": {
23
"foo": "bar"
24
}
25
},
26
"relationships": {
27
"shipping_category": {
28
"links": {...}
29
},
30
"prices": {
31
"links": {...}
32
},
33
"stock_items": {
34
"links": {...}
35
},
36
"delivery_lead_times": {
37
"links": {...}
38
},
39
"sku_options": {
40
"links": {...}
41
}
42
},
43
"meta": {
44
"mode": "test"
45
}
46
},
47
{
48
"other": "... 9 skus (first page)"
49
}
50
],
51
"meta": {
52
"record_count": 20,
53
"page_count": 2
54
},
55
"links": {
56
"first": "https://yourdomain.commercelayer.io/api/skus?filter[q][name_or_code_or_shipping_category_name_start]=TSHIRT&page[number]=1&page[size]=10",
57
"next": "https://yourdomain.commercelayer.io/api/skus?filter[q][name_or_code_or_shipping_category_name_start]=TSHIRT&page[number]=2&page[size]=10",
58
"last": "https://yourdomain.commercelayer.io/api/skus?filter[q][name_or_code_or_shipping_category_name_start]=TSHIRT&page[number]=2&page[size]=10"
59
}
60
}
Copied!
Last modified 5mo ago