The Category section of our API provides tools for managing product categories in your catalog. Using these methods, you can retrieve category information, create new ones, update existing ones, and manage their assignments and images. In this article, we will review the main methods available in this section of the API and their purposes.

Retrieving Category Information

To retrieve category information, send GET requests to the following endpoints:

  1. category.info - returns detailed information about a specific category by its ID. Use this endpoint to display category information on a product page, in a navigation menu, or within the admin panel.

  2. category.count - returns the total number of categories that match specific criteria (if any are provided in the request parameters). This can be useful for displaying statistics or for paginating category lists.

  3. category.list - returns a list of categories with support for filtering, sorting, and pagination. This method is the primary way to display category lists in your admin interface or catalog menu.

If your platform supports multistore functionality, you need to pass the store_id parameter to retrieve categories for a specific store. The list of all stores, along with their corresponding store_id values, can be retrieved using the cart.info method from the stores_info field.

Filling in all category fields may require multiple requests to the store for each category, which can affect the overall request execution time. To ensure optimal performance, we recommend retrieving only the response fields that are truly necessary for your business logic. For this purpose, the response_fields parameter is used. Read more about response fields filtering.

For pagination, use the page_cursor parameter. You need to pass a cursor that points to the next or previous page. The cursor values for the next or previous page are returned in the response of the list method.

"pagination": {
    "previous": null,
    "next": "Dc9ZgkMwAADQA%2FmImdLGZyy1jJYSCfkbDYraokqdfubd4Bn5adYKKdwaQyZIcq6mbdH3dh3CIzt7rbViEc8QtFF9DIoykQi4cLd7xacOZ620oE6PZA%2B2tCKlV%2B2c8H0%2BnWP5Tn8GdUsOkb23ZpQwQe2B7BXFVi1jvanPU3mY1JzJUHWvtbbE%2Fh33i%2BEnvVFlrirbqHboIjetty3xMq%2BxAF39fcTsAiSUg8aqRu%2FHvOmI468rrri5QguNjnmXP3a0QrmndGqAdsOOd1eMwHbBNGJRamyHOgvZPvQkJfl7vgih%2F8c4Hy84fGajT9IZu1ORhGW%2BIaz9ouFmzm0TJPyze2dbeQQsj9PsHa55ByfDCQ4PF8YN4P5XPaQBQCVfhTJ8Xn2b%2FfoELuyU7o4Q%2FRg9bap9H1%2FpQ%2FGmiEq3p1ooxR8%3D"
}

Note: Some platforms return only a cursor for the next page, meaning that pagination is only possible in the forward direction. In such cases, it's recommended to use additional filters to reduce the total number of categories that need to be paginated.

Most platforms support searching by specific fields. To perform a search, use the parameters find_value and find_where. The find_value parameter should contain the value to search for, while find_where should specify the field to search within.

Note: On some platforms, find_value supports partial string matching, while on others it only matches whole words.

To get a list of fields that can be used for searching on a specific platform, you can pass any clearly invalid value. The error message will include the list of supported searching fields.

{
    "return_code": 109,
    "return_message": "Parameter 'find_where' is not valid. The required type of parameter is string. The following values are allowed: name, description.",
    "result": {}
}

You can perform searches across multiple fields by specifying multiple values for find_where, separated by commas. For example: find_where=name,description.

Multilingual support is also available for categories on most platforms. To specify which language the category information should be returned in, you need to provide the lang_id parameter. The list of available languages for the store can be retrieved using the cart.info method, specifically from the store_languages field.

Most platforms support nested categories (category tree). For platforms like Salla and Mercadolibre, by default, the category.list method only returns top-level categories and their immediate child categories. To retrieve the next level of categories, you need to pass the id of the child category in the parent_id parameter.

For stores that support multistore functionality, each store may have its own separate category tree.

Note: On some platforms, especially marketplaces such as Amazon or eBay, the category.info method includes information that is not available in category.list. This includes fields like product_features and others, which describe product attributes required for items assigned to that category. These fields are essential when creating products. Here you can learn how to create a product on Amazon.

Category Management

The category.add method is used to create a new category. The request body must include data such as the category name, description, parent category (if applicable), and other required attributes.

To specify values for multilingual fields when creating a category, you need to include the lang_id parameter. If lang_id is not provided, the values will be set for the default language.

The stores_ids parameter allows you to assign the newly created category to multiple stores at once.

Note: you cannot create categories on marketplaces. Marketplaces have a global set of categories, which are often updated by the platform itself.

The category.update method allows you to update information for an existing category by its ID. The request body should include only the fields that need to be modified.

The category.delete method deletes a category by its ID. Use this method with caution, as deleting a category may affect related products and the overall catalog structure.

The category.image.add method is used to upload and associate an image with a specific category. The request body must include the category ID and a link to the image file.

The category.image.delete method removes the image associated with a specific category. You need to provide the category ID and the image ID.

The category.add.batch method allows you to create multiple categories at once, which can be useful for importing a large number of categories. This method also allows you to add images when creating categories.

The category.assign method allows you to assign a specified product to a specified category. The request body must include the category ID and the product ID.

The category.unassign method allows you to unassign a specified product from a specified category. The request body must include the category ID and the product ID.