The `search` module

Available Endpoints

The following endpoints are currently wrapped with a Model and SearchQuery subclass

Endpoint	Client Attribute	`SearchQuery` Subclass	`Model` Subclass
`orders`	`Client.orders`	`OrderSearch`	`Order`
`orders/items`	`Client.order_items`	`OrderItemSearch`	`OrderItem`
`invoices`	`Client.invoices`	`InvoiceSearch`	`Invoice`
`products`	`Client.products`	`ProductSearch`	`Product`
`products/attributes`	`Client.product_attributes`	`ProductAttributeSearch`	`ProductAttribute`
`categories`	`Client.categories`	`CategorySearch`	`Category`

class magento.search.SearchQuery(endpoint, client, model=<class 'magento.models.model.APIResponse'>)[source]View on GitHub 

Bases: object

Queries any endpoint that invokes the searchCriteria interface. Parent of all endpoint-specific search classes

Tip

See https://developer.adobe.com/commerce/webapi/rest/use-rest/performing-searches/ for official docs

__init__(endpoint, client, model=<class 'magento.models.model.APIResponse'>)[source]View on GitHub 

Initialize a SearchQuery object

Parameters

endpoint (str) – the base search API endpoint (for example, orders)
client (Client) – an initialized Client object
model (Type[Model]) – the Model to parse the response data with; uses APIResponse if not specified

client: The Client to send the search request with

endpoint: The endpoint being queried

Model: The magento.models subpackage class to wrap the response with

query: The current url for the search request

fields: Restricted fields, from restrict_fields()

add_criteria(field, value, condition='eq', **kwargs)[source]View on GitHub 

Add criteria to the search query

Parameters

field – the API response field to search by
value – the value of the field to compare
condition – the comparison condition
kwargs – additional search option arguments (group and filter)

Returns

the calling SearchQuery object

Return type

Self

Keyword Argument Options: Condition

The condition argument specifies the condition used to evaluate the attribute value

"eq" (default): matches items for which field=value
"gt": matches items for which field>value
"lt": matches items for which field<value
"gteq": matches items for which field>=value
"lteq": matches items for which field<=value
"in": matches items for which field in value.split(",")
- Tip: for in, use by_list() if not building a complex query

Example

# Search for Orders created in 2023
>>> orders = api.orders.add_criteria(
...     field="created_at",
...     value="2023-01-01",
...     condition='gteq'
... ).execute()

Keyword Argument Options: Using Filter Groups

group - filter group number

filter - filter number (within the specified filter group)

Using Filter Groups

Filter groups are filter criteria in the form of { field: value }

Group 0 Filter 0 -> Filter 0 Group 0 Filter 0 + Group 0 Filter 1 -> Filter 0 OR Filter 1 Group 0 Filter 0 + Group 1 Filter 0 -> Filter 0 AND Filter 0

restrict_fields(fields)[source]View on GitHub 

Constrain the API response data to only contain the specified fields

Parameters: fields (Iterable[str]) – an iterable or comma separated string of fields to include in the response
Returns: the calling SearchQuery object
Return type: Self

execute()[source]View on GitHub 

Sends the search request using the current scope of the client

Tip

Change the Client.scope to retrieve result data from different store views

Returns: the search query result
Return type: Optional[Union[Model, List[Model]]]

by_id(item_id)[source]View on GitHub 

Retrieve data for an individual item by its id

Note

The id field used is different depending on the endpoint being queried

Most endpoints use an entity_id or id
The orders/items endpoint uses item_id
The products endpoint uses product_id, but can also be queried by_sku()

The IDENTIFIER attribute of each Model contains the appropriate field

Parameters: item_id (Union[int, str]) – id of the item to retrieve
Return type: Optional[Model]

by_list(field, values)[source]View on GitHub 

Search for multiple items using an iterable or comma-separated string of field values

Examples

Retrieve Product with ids from 1 to 10:

# Values can be a list/tuple/iterable
>> api.products.by_list('entity_id', range(1,11))

Search for Order that are processing, pending, or completed:

#  Values can be a comma-separated string
>> api.orders.by_list('status', 'processing,pending,completed')

Parameters

field (str) – the API response field to search for matches in
values (Iterable) – an iterable or comma separated string of values

Return type

Optional[Model, List[Model]]

since(sinceDate=None)[source]View on GitHub 

Retrieve items for which created_at >= sinceDate

Example:

# Retrieve products created in 2023
>> api.products.since('2023-01-01').execute()

Tip

Calling with no arguments retrieves all items

# Retrieve all products
>> api.products.since().execute()

Parameters: sinceDate (str) – the date for response data to start from
Returns: the calling SearchQuery
Return type: Self

until(toDate)[source]View on GitHub 

Retrieve items for which created_at <= toDate

Parameters: toDate (str) – the date for response data to end at (inclusive)
Returns: the calling SearchQuery
Return type: Self

property result: Optional[Union[Model, List[Model]]]

The result of the search query, wrapped by the Model corresponding to the endpoint

Returns: the API response as either an individual or list of Model objects

validate_result()[source]View on GitHub 

Parses the response and returns the actual result data, regardless of search approach

Return type: Optional[Union[Dict, List[Dict]]]

parse(data)[source]View on GitHub 

Parses the API response with the corresponding Model object

Parameters: data (dict) – API response data of a single item
Return type: Model

reset()[source]View on GitHub 

Resets the query and result, allowing the object to be reused

property result_count: int: Number of items that matched the search criteria

property result_type: Type: The type of the result

property last_group: int

The most recent filter group on the query

Returns: the most recent filter group, or -1 if no criteria has been added

class magento.search.OrderSearch(client)[source]View on GitHub 

Bases: SearchQuery

SearchQuery subclass for the orders endpoint

__init__(client)[source]View on GitHub 

Initialize an OrderSearch

Parameters: client (Client) – an initialized Client object

by_number(order_number)[source]View on GitHub 

Retrieve an Order by number

Parameters: order_number (Union[int, str]) – the order number (increment_id)
Return type: Optional[Order]

by_product(product)[source]View on GitHub 

Search for all Order s of a Product

Parameters: product (Product) – the Product to search for in orders
Return type: Optional[Union[Order, List[Order]]]

by_sku(sku)[source]View on GitHub 

Search for Order by product sku

Note

Like OrderItemSearch.by_sku(), the sku will need to be an exact match to the sku of a simple product, including a custom option if applicable

Use by_product() or by_product_id() to find orders containing any of the option_skus and/or all children of a configurable product

Parameters: sku (str) – the exact product sku to search for in orders
Return type: Optional[Union[Order, List[Order]]]

by_product_id(product_id)[source]View on GitHub 

Search for Order s by product_id

Parameters: product_id (Union[int, str]) – the id (product_id) of the product to search for in orders
Return type: Optional[Union[Order, List[Order]]]

by_category_id(category_id, search_subcategories=False)[source]View on GitHub 

Search for Order s by category_id

Parameters

category_id (Union[int, str]) – id of the category to search for in orders
search_subcategories (bool) – if True, also searches for orders from all_subcategories

Returns

any Order containing a Product in the corresponding Category

Return type

Optional[Union[Order, List[Order]]]

by_category(category, search_subcategories=False)[source]View on GitHub 

Search for Order s that contain any of the category’s products

Parameters

category (Category) – the Category to use in the search
search_subcategories (bool) – if True, also searches for orders from all_subcategories

Returns

any Order that contains a product in the provided category

Return type

Optional[Union[Order, List[Order]]]

by_skulist(skulist)[source]View on GitHub 

Search for Order s using a list or comma separated string of product SKUs

Parameters: skulist (Union[str, Iterable[str]]) – an iterable or comma separated string of product SKUs
Return type: Optional[Union[Order, List[Order]]]

from_items(items)[source]View on GitHub 

Retrieve unique Order objects from OrderItem entries using a single request

Parameters: items (Optional[OrderItem | List[OrderItem]]) – an individual/list of order items
Return type: Optional[Order, List[Order]]

class magento.search.OrderItemSearch(client)[source]View on GitHub 

Bases: SearchQuery

SearchQuery subclass for the orders/items endpoint

__init__(client)[source]View on GitHub 

Initialize an OrderItemSearch

Parameters: client (Client) – an initialized Client object

property result: Optional[Union[OrderItem, List[OrderItem]]]

The result of the search query, wrapped by the Model corresponding to the endpoint

Returns: the API response as either an individual or list of Model objects

parse(data)[source]View on GitHub 

Overrides SearchQuery.parse() to fully hydrate OrderItem objects

Extra validation is required for OrderItems, as duplicated and/or incomplete data is returned when the child of a configurable product is searched by_sku() or by_product()

Parameters: data – API response data
Return type: Optional[OrderItem]

by_product(product)[source]View on GitHub 

Search for OrderItem entries by Product

Note

This will match OrderItems that contain

Any of the child products of a configurable product
Any of the option_skus of a product with custom options

Parameters: product (Product) – the Product to search for in order items
Return type: Optional[Union[OrderItem, List[OrderItem]]]

by_sku(sku)[source]View on GitHub 

Search for OrderItem entries by product sku.

The SKU must be an exact match to the OrderItem SKU

OrderItems always use the SKU of a simple product, including any custom options. This means that:

Searching the SKU of a configurable product returns nothing
If a product has custom options, the search will only find OrderItems that contain the specific option sku (or base sku) that’s provided

To search for OrderItems containing all children of a configurable product and/or all possible option_skus, use by_product() or by_product_id()

Parameters: sku (str) – the exact product sku to search for in order items
Return type: Optional[Union[OrderItem, List[OrderItem]]]

by_product_id(product_id)[source]View on GitHub 

Search for OrderItem entries by product id.

Parameters: product_id (Union[int, str]) – the id (product_id) of the Product to search for in order items
Return type: Optional[Union[OrderItem, List[OrderItem]]]

by_category_id(category_id, search_subcategories=False)[source]View on GitHub 

Search for OrderItem entries by category_id

Parameters

category_id (Union[int, str]) – id of the Category to search for in order items
search_subcategories (bool) – if True, also searches for order items from all_subcategories

Returns

any OrderItem containing a Product in the corresponding Category

Return type

Optional[Union[OrderItem, List[OrderItem]]]

by_category(category, search_subcategories=False)[source]View on GitHub 

Search for OrderItem entries that contain any of the category’s products

Parameters

category (Category) – the Category to use in the search
search_subcategories (bool) – if True, also searches for order items from all_subcategories

Return type

Optional[Union[OrderItem, List[OrderItem]]]

by_skulist(skulist)[source]View on GitHub 

Search for :class:`~.OrderItem`s using a list or comma-separated string of product SKUs

Parameters: skulist (Union[str, Iterable[str]]) – an iterable or comma separated string of product SKUs
Return type: Optional[Union[OrderItem, List[OrderItem]]]

class magento.search.InvoiceSearch(client)[source]View on GitHub 

Bases: SearchQuery

SearchQuery subclass for the invoices endpoint

__init__(client)[source]View on GitHub 

Initialize an InvoiceSearch

Parameters: client (Client) – an initialized Client object

by_number(invoice_number)[source]View on GitHub 

Retrieve an Invoice by number

Parameters: invoice_number (Union[int, str]) – the invoice number (increment_id)
Return type: Optional[Invoice]

by_order_number(order_number)[source]View on GitHub 

Retrieve an Invoice by order number

Parameters: order_number (Union[int, str]) – the order number (increment_id)
Return type: Optional[Invoice]

by_order(order)[source]View on GitHub 

Retrieve the Invoice for an Order

Parameters: order (Order) – the Order object to retrieve an invoice for
Return type: Optional[Invoice]

by_order_id(order_id)[source]View on GitHub 

Retrieve an Invoice by order_id

Parameters: order_id (Union[int, str]) – the order_id of the order to retrieve an invoice for
Return type: Optional[Invoice]

by_product(product)[source]View on GitHub 

Search for all Invoice s of a Product

Parameters: product (Product) – the Product to search for in invoices
Return type: Optional[Union[Invoice, List[Invoice]]]

by_sku(sku)[source]View on GitHub 

Search for Invoice s by product sku

Note

Like OrderItemSearch.by_sku(), the sku will need to be an exact match to the sku of a simple product, including a custom option if applicable

Use by_product() or by_product_id() to find orders containing any of the option_skus and/or all children of a configurable product

Parameters: sku (str) – the exact product sku to search for in invoices
Return type: Optional[Union[Invoice, List[Invoice]]]

by_product_id(product_id)[source]View on GitHub 

Search for Invoice s by product_id

Parameters: product_id (Union[int, str]) – the id (product_id) of the product to search for in invoices
Return type: Optional[Union[Invoice, List[Invoice]]]

by_category_id(category_id, search_subcategories=False)[source]View on GitHub 

Search for Invoice s by category_id

Parameters

category_id (Union[int, str]) – id of the category to search for in orders
search_subcategories (bool) – if True, also searches for orders from all_subcategories

Returns

any Invoice containing a Product in the corresponding Category

Return type

Optional[Union[Invoice, List[Invoice]]]

by_category(category, search_subcategories=False)[source]View on GitHub 

Search for Invoice s that contain any of the category’s products

Parameters

category (Category) – the Category to use in the search
search_subcategories (bool) – if True, also searches for orders from all_subcategories

Returns

any Invoice that contains a product in the provided category

Return type

Optional[Union[Invoice, List[Invoice]]]

by_skulist(skulist)[source]View on GitHub 

Search for Invoice s using a list or comma separated string of product SKUs

Parameters: skulist (Union[str, Iterable[str]]) – an iterable or comma separated string of product SKUs
Return type: Optional[Union[Invoice, List[Invoice]]]

from_order_items(items)[source]View on GitHub 

Retrieve unique Invoice objects from OrderItem entries using a single request

Tip

Since there is no invoices/items endpoint, to search for invoices we must first do an OrderItemSearch, then retrieve the order_ids and search by_order_id()

Parameters: items (Optional[OrderItem | List[OrderItem]]) – an individual/list of order items
Return type: Optional[Invoice, List[Invoice]]

class magento.search.ProductSearch(client)[source]View on GitHub 

Bases: SearchQuery

SearchQuery subclass for the products endpoint

__init__(client)[source]View on GitHub 

Initialize a ProductSearch

Parameters: client (Client) – an initialized Client object

property attributes: ProductAttributeSearch: Alternate way to access the SearchQuery for ProductAttribute data

by_id(item_id)[source]View on GitHub 

Retrieve a Product by product_id

Note

Response data from the products endpoint only has an id field, but all other endpoints that return data about products will use product_id

Parameters: item_id (Union[int, str]) – the id (product_id) of the product
Return type: Optional[Product]

by_sku(sku)[source]View on GitHub 

Retrieve a Product by sku

Parameters: sku – the product sku
Return type: Optional[Product]

by_skulist(skulist)[source]View on GitHub 

Search for :class:`~.Product`s using a list or comma separated string of SKUs

Parameters: skulist (Union[str, Iterable[str]]) – an iterable or comma separated string of SKUs
Return type: Optional[Union[Product, List[Product]]]

by_category(category, search_subcategories=False)[source]View on GitHub 

Search for Product s in a Category

Parameters

category (Category) – the Category to retrieve products from
search_subcategories (bool) – if True, also retrieves products from all_subcategories

Return type

Optional[Union[Product, List[Product]]]

by_category_id(category_id, search_subcategories=False)[source]View on GitHub 

Search for Product s by category_id

Parameters

category_id (Union[int, str]) – the id of the Category to retrieve products from
search_subcategories (bool) – if True, also retrieves products from all_subcategories

Return type

Optional[Union[Product, List[Product]]]

get_stock(sku)[source]View on GitHub 

Retrieve the stock of a product by sku

Parameters: sku – the product sku
Return type: Optional[int]

class magento.search.ProductAttributeSearch(client)[source]View on GitHub 

Bases: SearchQuery

SearchQuery subclass for the products/attributes endpoint

__init__(client)[source]View on GitHub 

Initialize a ProductAttributeSearch

Parameters: client (Client) – an initialized Client object

get_all()[source]View on GitHub 

Retrieve a list of all :class:`~.ProductAttribute`s

Return type: Optional[List[ProductAttribute]]

by_code(attribute_code)[source]View on GitHub 

Retrieve a ProductAttribute by its attribute code

Parameters: attribute_code (str) – the code of the ProductAttribute
Return type: Optional[ProductAttribute]

get_types()[source]View on GitHub 

Retrieve a list of all available ProductAttribute types

Return type: Optional[List[APIResponse]]

class magento.search.CategorySearch(client)[source]View on GitHub 

Bases: SearchQuery

SearchQuery subclass for the categories endpoint

__init__(client)[source]View on GitHub 

Initialize a CategorySearch

Parameters: client (Client) – an initialized Client object

get_root()[source]View on GitHub 

Retrieve the top level/default Category (every other category is a subcategory)

Return type: Category

get_all()[source]View on GitHub 

Retrieve a list of all categories

Return type: List[Category]

by_name(name, exact=True)[source]View on GitHub 

Search for a Category by name

Parameters

name (str) – the category name to search for
exact (bool) – whether the name should be an exact match

Return type

Optional[Union[Category, List[Category]]]

The search module

Available Endpoints

The `search` module