The search
moduleο
Available Endpointsο
The following endpoints are currently wrapped with a Model
and SearchQuery
subclass
Endpoint |
Client Attribute |
|
|
|||
---|---|---|---|---|---|---|
|
||||||
|
||||||
|
||||||
|
||||||
|
||||||
|
- 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
- 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
andfilter
)
- 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 whichfield=value
"gt"
: matches items for whichfield>value
"lt"
: matches items for whichfield<value
"gteq"
: matches items for whichfield>=value
"lteq"
: matches items for whichfield<=value
"in"
: matches items for whichfield in value.split(",")
Tip: for
in
, useby_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 numberfilter
- 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 theclient
Tip
Change the
Client.scope
to retrieveresult
data from different storeviews
- 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 queriedMost endpoints use an
entity_id
orid
The
orders/items
endpoint usesitem_id
The
products
endpoint usesproduct_id
, but can also be queriedby_sku()
The
IDENTIFIER
attribute of eachModel
contains the appropriate field
- 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')
- 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
- parse(data)[source]View on GitHubο
Parses the API response with the corresponding
Model
object
- reset()[source]View on GitHubο
Resets the query and result, allowing the object to be reused
- class magento.search.OrderSearch(client)[source]View on GitHubο
Bases:
SearchQuery
SearchQuery
subclass for theorders
endpoint- __init__(client)[source]View on GitHubο
Initialize an
OrderSearch
- by_number(order_number)[source]View on GitHubο
Retrieve an
Order
by number
- by_product(product)[source]View on GitHubο
- by_sku(sku)[source]View on GitHubο
Search for
Order
by product skuNote
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 applicableUse
by_product()
orby_product_id()
to find orders containing any of theoption_skus
and/or allchildren
of a configurable product
- by_product_id(product_id)[source]View on GitHubο
Search for
Order
s byproduct_id
- by_category_id(category_id, search_subcategories=False)[source]View on GitHubο
Search for
Order
s bycategory_id
- by_category(category, search_subcategories=False)[source]View on GitHubο
Search for
Order
s that contain any of the categoryβsproducts
- by_skulist(skulist)[source]View on GitHubο
Search for
Order
s using a list or comma separated string of product SKUs
- class magento.search.OrderItemSearch(client)[source]View on GitHubο
Bases:
SearchQuery
SearchQuery
subclass for theorders/items
endpoint- __init__(client)[source]View on GitHubο
Initialize an
OrderItemSearch
- 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 hydrateOrderItem
objectsExtra validation is required for OrderItems, as duplicated and/or incomplete data is returned when the child of a configurable product is searched
by_sku()
orby_product()
- by_product(product)[source]View on GitHubο
Search for
OrderItem
entries byProduct
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
- 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 possibleoption_skus
, useby_product()
orby_product_id()
- by_product_id(product_id)[source]View on GitHubο
Search for
OrderItem
entries by product id.
- by_category_id(category_id, search_subcategories=False)[source]View on GitHubο
Search for
OrderItem
entries bycategory_id
- by_category(category, search_subcategories=False)[source]View on GitHubο
Search for
OrderItem
entries that contain any of the categoryβsproducts
- class magento.search.InvoiceSearch(client)[source]View on GitHubο
Bases:
SearchQuery
SearchQuery
subclass for theinvoices
endpoint- __init__(client)[source]View on GitHubο
Initialize an
InvoiceSearch
- by_number(invoice_number)[source]View on GitHubο
Retrieve an
Invoice
by number
- by_order_number(order_number)[source]View on GitHubο
Retrieve an
Invoice
by order number
- by_order(order)[source]View on GitHubο
- by_order_id(order_id)[source]View on GitHubο
Retrieve an
Invoice
byorder_id
- by_product(product)[source]View on GitHubο
- by_sku(sku)[source]View on GitHubο
Search for
Invoice
s by product skuNote
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 applicableUse
by_product()
orby_product_id()
to find orders containing any of theoption_skus
and/or allchildren
of a configurable product
- by_product_id(product_id)[source]View on GitHubο
Search for
Invoice
s byproduct_id
- by_category_id(category_id, search_subcategories=False)[source]View on GitHubο
Search for
Invoice
s bycategory_id
- by_category(category, search_subcategories=False)[source]View on GitHubο
Search for
Invoice
s that contain any of the categoryβsproducts
- by_skulist(skulist)[source]View on GitHubο
Search for
Invoice
s using a list or comma separated string of product SKUs
- from_order_items(items)[source]View on GitHubο
Retrieve unique
Invoice
objects fromOrderItem
entries using a single requestTip
Since there is no
invoices/items
endpoint, to search for invoices we must first do anOrderItemSearch
, then retrieve theorder_ids
and searchby_order_id()
- class magento.search.ProductSearch(client)[source]View on GitHubο
Bases:
SearchQuery
SearchQuery
subclass for theproducts
endpoint- __init__(client)[source]View on GitHubο
Initialize a
ProductSearch
- property attributes: ProductAttributeSearchο
Alternate way to access the SearchQuery for
ProductAttribute
data
- by_id(item_id)[source]View on GitHubο
Retrieve a
Product
byproduct_id
Note
Response data from the
products
endpoint only has anid
field, but all other endpoints that return data about products will useproduct_id
- by_sku(sku)[source]View on GitHubο
Retrieve a
Product
bysku
- by_skulist(skulist)[source]View on GitHubο
Search for :class:`~.Product`s using a list or comma separated string of SKUs
- by_category(category, search_subcategories=False)[source]View on GitHubο
- by_category_id(category_id, search_subcategories=False)[source]View on GitHubο
Search for
Product
s bycategory_id
- class magento.search.ProductAttributeSearch(client)[source]View on GitHubο
Bases:
SearchQuery
SearchQuery
subclass for theproducts/attributes
endpoint- __init__(client)[source]View on GitHubο
Initialize a
ProductAttributeSearch
- get_all()[source]View on GitHubο
Retrieve a list of all :class:`~.ProductAttribute`s
- Return type
- 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
- get_types()[source]View on GitHubο
Retrieve a list of all available
ProductAttribute
types- Return type
- class magento.search.CategorySearch(client)[source]View on GitHubο
Bases:
SearchQuery
SearchQuery
subclass for thecategories
endpoint- __init__(client)[source]View on GitHubο
Initialize a
CategorySearch
- get_root()[source]View on GitHubο
Retrieve the top level/default
Category
(every other category is a subcategory)- Return type
- get_all()[source]View on GitHubο
Retrieve a list of all categories