Edit in GitHubLog an issue

Search using REST endpoints

POST, PUT, and DELETE requests to the REST Web API require the service method parameters to be in the body of the request. For example, to create a Customer, you would specify a JSON array (or XML structure) in the body of the message.

For search APIs that invoke a *Repository::getList(SearchCriteriaInterface *) call, the searchCriteria must be specified in the URL of the GET request. The basic pattern for specifying the criteria is

Copied to your clipboard
1searchCriteria[filter_groups][<index>][filters][<index>][field]=<field_name>
2searchCriteria[filter_groups][<index>][filters][<index>][value]=<search_value>
3searchCriteria[filter_groups][<index>][filters][<index>][condition_type]=<operator>

where:

  • field is an attribute name.
  • value specifies the value to search for.
  • condition_type is one of the following values:
ConditionNotes
eqEquals
finsetA value within a set of values
fromThe beginning of a range. Must be used with to.
gtGreater than
gteqGreater than or equal
inIn. The value can contain a comma-separated list of values.
likeLike. The value can contain the SQL wildcard characters when like is specified.
ltLess than
lteqLess than or equal
moreqMore or equal
neqNot equal
nfinsetA value that is not within a set of values.
ninNot in. The value can contain a comma-separated list of values.
nlikeNot like
notnullNot null
nullNull
toThe end of a range. Must be used with from.

The filter_groups array defines one or more filters. Each filter defines a search term, and the field, value, and condition_type of a search term must be assigned the same index number, starting with 0. Increment additional terms as needed.

When constructing a search, keep the following in mind:

  • To perform a logical OR, specify multiple filters within a filter_groups.
  • To perform a logical AND, specify multiple filter_groups.
  • You cannot perform a logical OR across different filter_groups, such as (A AND B) OR (X AND Y). ORs can be performed only within the context of a single filter_groups.
  • You can only search top-level attributes.

The following sections provide examples of each type of search. These examples use the Magento Open Source sample data.

Simple search#

The Magento Open Source sample data uses the category_gear field to describe the categories for each item listed under Gear on sample store. Each item can be assigned to multiple categories. Electronics are assigned the code 86. The following example returns all gear tagged as electronics.

Copied to your clipboard
1GET <host>/rest/<store_code>/V1/products/?
2searchCriteria[filter_groups][0][filters][0][field]=category_gear&
3searchCriteria[filter_groups][0][filters][0][value]=86&
4searchCriteria[filter_groups][0][filters][0][condition_type]=finset

The system creates an array, as shown in the following pseudo-code.

Copied to your clipboard
1searchCriteria => [
2  'filterGroups' => [
3    0 => [
4      'filters' => [
5         0 => [
6           'field' => 'category_gear',
7           'value' => '86',
8           'condition_type' => 'finset'
9         ]
10      ]
11    ]
12  ]

The query returns 9 items.

Simple search using a timestamp#

The following search finds all invoices created after the specified time (midnight, July 1 2016). You can set up a similar search to run periodically to poll for changes.

Copied to your clipboard
1GET <host>/rest/<store_code>/V1/invoices?
2searchCriteria[filter_groups][0][filters][0][field]=created_at&
3searchCriteria[filter_groups][0][filters][0][value]=2016-07-01 00:00:00&
4searchCriteria[filter_groups][0][filters][0][condition_type]=gt

Simple search using an in conditions type#

The following search finds all the products that are provided in the value field. When you specify the in condition type, the value field must be a comma separated list.

Copied to your clipboard
1GET <host>/rest/<store_code>/V1/products?
2searchCriteria[filter_groups][0][filters][0][field]=entity_id&
3searchCriteria[filter_groups][0][filters][0][value]=1,2,3,4,5&
4searchCriteria[filter_groups][0][filters][0][condition_type]=in

The query returns 5 items.

Logical OR search#

The following example searches for all products whose names contain the string Leggings or Parachute. The instances of %25 in the example are converted into the SQL wildcard character %.

Copied to your clipboard
1GET <host>/rest/<store_code>/V1/products?
2searchCriteria[filter_groups][0][filters][0][field]=name&
3searchCriteria[filter_groups][0][filters][0][value]=%25Leggings%25&
4searchCriteria[filter_groups][0][filters][0][condition_type]=like&
5searchCriteria[filter_groups][0][filters][1][field]=name&
6searchCriteria[filter_groups][0][filters][1][value]=%25Parachute%25&
7searchCriteria[filter_groups][0][filters][1][condition_type]=like

The system creates an array, as shown in the following pseudo-code.

Copied to your clipboard
1searchCriteria => [
2  'filterGroups' => [
3    0 => [
4      'filters' => [
5         0 => [
6           'field' => 'name',
7           'value' => '%25Leggings%25',
8           'condition_type' => 'like'
9         ]
10         1 => [
11          'field' => 'name',
12          'value' => '%25Parachute%25',
13          'condition_type' => 'like'
14         ]
15      ]
16    ]
17  ]

The search returns 14 products that contain the string Leggings in the name field and 14 products that contain the string Parachute.

Logical AND search#

This sample searches for women's shorts that are size 31 and costs less than $30. In the CE sample data, women's shorts have a sku value that begins with WSH. The sku also contains the size and color, such as WSH02-31-Yellow.

Copied to your clipboard
1GET <host>/rest/<store_code>/V1/products?
2searchCriteria[filter_groups][0][filters][0][field]=sku&
3searchCriteria[filter_groups][0][filters][0][value]=WSH%2531%25&
4searchCriteria[filter_groups][0][filters][0][condition_type]=like&
5searchCriteria[filter_groups][1][filters][0][field]=price&
6searchCriteria[filter_groups][1][filters][0][value]=30&
7searchCriteria[filter_groups][1][filters][0][condition_type]=lt

The system creates an array, as shown in the following pseudo-code.

Copied to your clipboard
1searchCriteria => [
2  'filterGroups' => [
3    0 => [
4      'filters' => [
5         0 => [
6           'field' => 'sku',
7           'value' => 'WSH%31%',
8           'condition_type' => 'like'
9         ]
10    1 => [
11 'filters' => [
12         0 => [
13          'field' => 'price',
14          'value' => '30',
15          'condition_type' => 'lt'
16         ]
17      ]
18    ]
19  ]

The query returns 9 items.

Logical AND and OR search#

This sample is similar the Logical AND sample. It searches the skus for women's shorts (WSH%) or pants (WP%)in size 29. The system performs two logical ANDs to restrict the results to those that cost from $40 to $49.99

Copied to your clipboard
1GET <host>/rest/<store_code>/V1/products?
2searchCriteria[filter_groups][0][filters][0][field]=sku&
3searchCriteria[filter_groups][0][filters][0][value]=WSH%2529%25&
4searchCriteria[filter_groups][0][filters][0][condition_type]=like&
5searchCriteria[filter_groups][0][filters][1][field]=sku&
6searchCriteria[filter_groups][0][filters][1][value]=WP%2529%25&
7searchCriteria[filter_groups][0][filters][1][condition_type]=like&
8searchCriteria[filter_groups][1][filters][0][field]=price&
9searchCriteria[filter_groups][1][filters][0][value]=40&
10searchCriteria[filter_groups][1][filters][0][condition_type]=from&
11searchCriteria[filter_groups][2][filters][0][field]=price&
12searchCriteria[filter_groups][2][filters][0][value]=49.99&
13searchCriteria[filter_groups][2][filters][0][condition_type]=to

The query returns 37 items.

Other search criteria#

The following searchCriteria can be used to determine the sort order and the number of items to return.

  • searchCriteria[sortOrders][<index>][field]=<field-name> - Specifies the field to sort on. By default, search results are returned in descending order. You can sort on multiple fields. For example, to sort on price first and then by name, call searchCriteria[sortOrders][0][field]=price&searchCriteria[sortOrders][1][field]=name.

  • searchCriteria[sortOrders][<index>][direction]=ASC | DESC - Specifies whether to return results in ascending (ASC) or descending (DESC) order. To expand the previous example and sort the price fields in descending order and the name fields in ascending order, call searchCriteria[sortOrders][0][field]=price&searchCriteria[sortOrders][1][field]=name&searchCriteria[sortOrders][1][direction]=ASC.

  • searchCriteria[pageSize] - Specifies the maximum number of items to return. The value must be an integer. If the pageSize is not specified, the system returns all matches.

  • searchCriteria[currentPage] - Returns the current page.

Example for search criteria to determine the sort order and attributes to return#

This example shows how to use search criteria to determine the sort order and attributes to return. It returns orders with status pending.

Endpoint:

GET <host>/rest/<store_code>/V1/orders/

Headers:

Content-Type application/json

Authorization Bearer <administrator token>

Parameters:

ParameterValueDescription
searchCriteria[filter_groups][0][filters][0][field]statusAttribute name to filter
searchCriteria[filter_groups][0][filters][0][value]pendingAttribute value to filter
fieldsitems[increment_id,entity_id]Attributes to return in the response. If you do not specify this parameter, all attributes will be returned.

Payload:

Not applicable

Request:

Copied to your clipboard
1GET <host>/rest/V1/orders?
2searchCriteria[filter_groups][0][filters][0][field]=status&
3searchCriteria[filter_groups][0][filters][0][value]=pending&
4searchCriteria[sortOrders][0][field]=increment_id&
5fields=items[increment_id,entity_id]

Response:

Copied to your clipboard
1{
2 "items": [
3 {
4 "entity_id": 3003,
5 "increment_id": "WA0003003"
6 },
7 {
8 "entity_id": 3140,
9 "increment_id": "WA0003140"
10 },
11 {
12 "entity_id": 9435,
13 "increment_id": "WA0009435"
14 }
15 ]
16}
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.