The `search` module

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

Options

condition: condition used to evaluate the attribute value

(Default Value) ‘eq’ = (field=value)
‘gt’ > ‘lt’ < ‘gteq’ >= ‘lteq’ <= ‘in’ []

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

Example

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

#  Values can be a list/tuple/iterable
>> api.orders.by_list('status', ['processing', 'pending', '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]]

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

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[Order, List[Order]]]

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

The `search` module