Efficiently Retrieve Categories and Products Using Magento's Search Criteria API

Magento is a powerful e-commerce platform that offers a robust API for managing your online store. One of the key features of this API is the Search Criteria functionality, which allows you to filter, sort, and paginate through various entities like products, customers, orders, and categories. In this post, we'll dive into how to use Magento's Search Criteria API to retrieve lists of categories and products efficiently.

Why Use the Search Criteria API?

The Search Criteria API in Magento provides a flexible and efficient way to query your store's data. Whether you need to fetch specific categories or products based on certain attributes, sort them in a particular order, or limit the number of results, this API makes it straightforward to tailor your queries to your exact needs.

Step-by-Step Guide to Retrieving Categories and Products

Let's walk through examples where we'll filter and sort categories and products, and limit the results to 5 items per page.

Step 1: Authentication

Before you can make any requests to the Magento API, you'll need to obtain an access token. This token will authenticate your requests.

curl -X POST "https://your-magento-site.com/rest/V1/integration/admin/token" \
     -H "Content-Type: application/json" \
     -d '{"username":"your-username", "password":"your-password"}'

The response will be an access token, which you'll use in subsequent API requests.

Retrieving Categories

We want to create a search criteria that filters categories by name, sorts them by ID, and limits the results to 5 items per page. Here's how to construct the request URL and make the API call:

Request URL

https://your-magento-site.com/rest/V1/categories/list?searchCriteria[filterGroups][0][filters][0][field]=name&searchCriteria[filterGroups][0][filters][0][value]=%25&searchCriteria[filterGroups][0][filters][0][conditionType]=like&searchCriteria[sortOrders][0][field]=id&searchCriteria[sortOrders][0][direction]=ASC&searchCriteria[pageSize]=5&searchCriteria[currentPage]=1

cURL Command

curl -X GET "https://your-magento-site.com/rest/V1/categories/list?searchCriteria[filterGroups][0][filters][0][field]=name&searchCriteria[filterGroups][0][filters][0][value]=%25&searchCriteria[filterGroups][0][filters][0][conditionType]=like&searchCriteria[sortOrders][0][field]=id&searchCriteria[sortOrders][0][direction]=ASC&searchCriteria[pageSize]=5&searchCriteria[currentPage]=1" \
     -H "Authorization: Bearer your-access-token"

Explanation of Parameters

• searchCriteria[filterGroups][0][filters][0][field]=name: Filter by the name field.
• searchCriteria[filterGroups][0][filters][0][value]=%25: Use a wildcard search (% matches any name).
• searchCriteria[filterGroups][0][filters][0][conditionType]=like: The condition type is like (similar to SQL LIKE operator).
• searchCriteria[sortOrders][0][field]=id: Sort the results by the id field.
• searchCriteria[sortOrders][0][direction]=ASC: Sort in ascending order.
• searchCriteria[pageSize]=5: Limit the number of results to 5.
• searchCriteria[currentPage]=1: Retrieve the first page of results.

Response

The response will be a JSON object containing the filtered and sorted category list, along with additional metadata about the results.

{
  "items": [
    {
      "id": 1,
      "parent_id": 0,
      "name": "Default Category",
      "is_active": true,
      // other category fields...
    },
    {
      "id": 2,
      "parent_id": 1,
      "name": "Category 1",
      "is_active": true,
      // other category fields...
    }
    // up to 5 categories...
  ],
  "search_criteria": {
    "filter_groups": [
      {
        "filters": [
          {
            "field": "name",
            "value": "%",
            "condition_type": "like"
          }
        ]
      }
    ],
    "sort_orders": [
      {
        "field": "id",
        "direction": "ASC"
      }
    ],
    "page_size": 5,
    "current_page": 1
  },
  "total_count": 10
}

Retrieving Products

Now, let's create a search criteria that filters products by SKU, sorts them by price, and limits the results to 5 items per page.

Request URL

https://your-magento-site.com/rest/V1/products?searchCriteria[filterGroups][0][filters][0][field]=sku&searchCriteria[filterGroups][0][filters][0][value]=%25&searchCriteria[filterGroups][0][filters][0][conditionType]=like&searchCriteria[sortOrders][0][field]=price&searchCriteria[sortOrders][0][direction]=ASC&searchCriteria[pageSize]=5&searchCriteria[currentPage]=1

cURL Command

curl -X GET "https://your-magento-site.com/rest/V1/products?searchCriteria[filterGroups][0][filters][0][field]=sku&searchCriteria[filterGroups][0][filters][0][value]=%25&searchCriteria[filterGroups][0][filters][0][conditionType]=like&searchCriteria[sortOrders][0][field]=price&searchCriteria[sortOrders][0][direction]=ASC&searchCriteria[pageSize]=5&searchCriteria[currentPage]=1" \
     -H "Authorization: Bearer your-access-token"

Explanation of Parameters

• searchCriteria[filterGroups][0][filters][0][field]=sku: Filter by the sku field.
• searchCriteria[filterGroups][0][filters][0][value]=%25: Use a wildcard search (% matches any SKU).
• searchCriteria[filterGroups][0][filters][0][conditionType]=like: The condition type is like (similar to SQL LIKE operator).
• searchCriteria[sortOrders][0][field]=price: Sort the results by the price field.
• searchCriteria[sortOrders][0][direction]=ASC: Sort in ascending order.
• searchCriteria[pageSize]=5: Limit the number of results to 5.
• searchCriteria[currentPage]=1: Retrieve the first page of results.

Response

The response will be a JSON object containing the filtered and sorted product list, along with additional metadata about the results.

{
  "items": [
    {
      "id": 1,
      "sku": "product-1",
      "name": "Product 1",
      "price": 10.00,
      // other product fields...
    },
    {
      "id": 2,
      "sku": "product-2",
      "name": "Product 2",
      "price": 15.00,
      // other product fields...
    }
    // up to 5 products...
  ],
  "search_criteria": {
    "filter_groups": [
      {
        "filters": [
          {
            "field": "sku",
            "value": "%",
            "condition_type": "like"
          }
        ]
      }
    ],
    "sort_orders": [
      {
        "field": "price",
        "direction": "ASC"
      }
    ],
    "page_size": 5,
    "current_page": 1
  },
  "total_count": 50
}

Conclusion

Using Magento's Search Criteria API, you can efficiently retrieve and manage categories and products based on specific criteria. This powerful feature allows you to tailor your queries to meet your exact needs, making data retrieval straightforward and efficient. By following the steps outlined in this post, you can start leveraging the Search Criteria API to enhance your Magento store's data management capabilities.

Feel free to adapt and expand upon these examples to suit your specific use cases. Happy coding!