Endpoint Summary
This table provides quick access to the category query service under the Category section. Detailed request and response fields are included under the relevant section.
| No | Service | Endpoint |
|---|---|---|
| 1 | Category Query | POST /api/v1/query/categories |
General Technical Information
For the Category query endpoint on this page, authentication information is sent in the request body.
ClientId and AppKey fields are required.
This section is prepared to query the category records used to classify products hierarchically within the catalog. The endpoint does not create or update data; it lists existing category definitions.
The category tree is interpreted through the ParentId and, if available, Children fields.
For root categories, ParentId can be empty or null.
The IsLeaf field indicates whether the category is a final-level category.
This field can be critical in product assignment and category-based filtering scenarios.
Records are returned in the Result field, while the total record count is returned in the TotalCount field.
Category is the catalog structure that enables products to be classified under logical groups according to their common characteristics. A properly structured category setup is a key reference data source for product listing, filtering, search, and user navigation.
Category information can be used to display products in the correct catalog position, enable category-based filters, and manage business rules such as campaigns or commissions through product groups.
1. Category Query — POST /api/v1/query/categories
This endpoint is used to retrieve the data shown in the Categories list and category tree structure in the PIM UI through the API.
GetCategoriesis used to query category records centrally defined in PIM.CategoryIdsparameter can be used to query specific category records by ID.Names,IncludesNames, andExcludesNamesparameters are used in filtering scenarios by category name.CodesandIntegrationCodesfields can be used as references when matching categories with external systems.IncludeFullNamesfield enables the full path information of the category hierarchy to be returned in the response.DimensionIdcan be used to interpret the dimension or classification structure to which the category belongs.
Usage Notes for Category Data
- The category structure is the main reference data for listing products under the correct catalog breakdown.
- The category hierarchy can be used to create menus, breadcrumbs, and category filters on the marketplace or storefront side.
- In product assignment processes, the
IsLeaffield should be checked for final-level categories. - In multi-system integrations, it is recommended to use
CodeorIntegrationCodeinstead of only the category name when matching categories. - The
Statusfield can be used to interpret the active/passive status of the category record.
Endpoint-Specific Query Parameters
| API Parameter | Type | PIM UI Equivalent / Meaning | Description |
|---|---|---|---|
CategoryIds | array (integer) | Category System ID List | Used to filter specific categories by ID. |
Names | array (string) | Category Name Filter | Exact-match filter by category name. |
IncludesNames | array (string) | Category Names Containing | Returns category names that contain the specified texts. |
ExcludesNames | array (string) | Excluded Category Names | Excludes categories that contain the specified texts. |
Codes | array (string) | Category Code Filter | Filters by the Code field of the category. |
IntegrationCodes | array (string) | Integration Code Filter | Filters by the integration code of the category. |
DimensionIds | array (integer) | Dimension ID Filter | Filters by specific dimension definitions. |
IncludeFullNames | boolean | Include Full Path Name | When set to true, returns the full path name of the category hierarchy, such as Clothing > Tops > T-Shirt. |
API Response Parameters and UI Equivalents
Each Category object in the Result array contains the following fields:
| API Response Field | Type | PIM UI Equivalent / Field Name | Description |
|---|---|---|---|
CategoryId | integer | Category System ID | Unique category number assigned by the system. |
ParentId | integer? | Parent Category ID | ID of the parent category in the hierarchy. null is returned for root categories. |
Name | string | Category Name | Name displayed in the category tree and list in the UI. |
Code | string | Category Code | Unique code of the category. |
IntegrationCode | string | Integration Code | External system matching code. |
ShortDescription | string | Short Description | Short description in the category detail. |
LongDescription | string | Long Description | Long description in the category detail. |
SortOrder | integer | Sort Order | Display order in the category tree in the UI. |
IsLeaf | boolean | Is Leaf Category? | true means it is the final node/category with no child categories. |
DimensionId | integer | Dimension ID | Dimension definition to which the category belongs. |
Children | array | Child Categories | List of child categories under the category. |
Products | array | Products in the Category | List of products linked to the category. |
Pictures | array | Category Images | Images assigned to the category. |
Properties | array | Category Properties | Custom fields defined for the category. |
Filters | array | Category Filters | Filter configurations defined for the category. |
Tags | array | Category Tags | Tags assigned to the category. |
Translations | array | Multilingual Values | Translations of the category name and descriptions. |
Status | integer | Status | 1 = Active, -1 = Passive. |
Created | datetime | Creation Date | Date when the category was added to the system. |
Updated | datetime? | Update Date | Last update date. |
Usage Guide in the UI
- Category Tree: The hierarchical category tree you see in the left panel of the UI is created using the
ParentIdandChildrenfields. Categories withParentId = nullare root nodes. - Full Path Name: By sending
IncludeFullNames = true, you can retrieve the full category path in theClothing > Tops > T-Shirtformat displayed in the product list in the UI. - Leaf Category: Products are generally assigned only to leaf categories (
IsLeaf = true).
Common Error Cases
The table below is prepared for the common error cases that may apply to the endpoint under the Category section. When endpoint-specific error messages are finalized, they can be added to the Error Message column.
| HTTP Status | Status | Error Message |
|---|---|---|
400 | Bad Request | |
401 | Unauthorized | |
403 | Forbidden | |
404 | Not Found | |
422 | Unprocessable Entity | |
429 | Too Many Requests | |
500 | Internal Server Error |