Category Management
Overview
The Categories API allows you to search, browse, and manage product categories in the SellerCenter catalog. Categories are hierarchical organizational structures that group products by type, helping customers navigate and find products efficiently.
Categories in SellerCenter have multiple characteristics:
- Hierarchical structure: Categories can have parent-child relationships, creating a tree structure
- Status management: Categories can be active, inactive, inherited_inactive, or deleted
- Visibility controls: Categories can be visible to customers, visible in fulfillment/consignment, and have quality-control settings
- Attribute sets: Each category is associated with an attribute set that defines which product attributes are required
- Serial number requirements: Some categories require products to have serial numbers
Search Categories
GET /v2/categories
Summary: Get the categories for the provided search query. When search query is empty or not included in the request then endpoint can be used to paginate throw all categories.
Description: This endpoint allows you to search for categories by query string or paginate through all available categories. When a search query is provided, the endpoint filters categories by name. When no search query is provided, the endpoint returns all categories based on pagination parameters.
The endpoint supports the includeInaccessible parameter to control whether restricted categories are included in the results. By default, only categories accessible to your seller account are returned.
Note: This endpoint returns detailed category information including:
- Category identifiers (
id,uuid) - Hierarchical information (
parentId,pathIds,path,childrenIds) - Attribute set association (
attributeSetId) - Visibility and status flags (
visible,fulfillmentVisible,qcDisabled,serialNumberRequired,status)
Important:
- The
limitandoffsetparameters are required for pagination - Maximum
limitvalue depends on your system configuration (typically 100) - Use the
queryparameter to search categories by name (partial matching is supported) - Categories with status
inactiveorinherited_inactiveshould not be used for new product assignments - The
pathfield provides the full category path as an array of names (e.g., ["Fashion", "Women", "Shoes"])
Get Category by ID
GET /v2/category/{categoryId}
Summary: Get the category for the provided id.
Description: Get some information about a category based on its id. This is not related to a particular seller, so the properties (eg visibility) are not altered in any way.
Get Categories by IDs
GET /v2/categories/ids
Summary: Get the categories for the provided ids.
Description: This endpoint allows you to retrieve specific categories by providing their IDs. This is useful when you already know the category IDs and need to fetch their details in bulk, rather than searching or paginating through all categories.
The endpoint supports pagination through the limit and offset parameters, and the includeInaccessible parameter to control whether restricted categories are included in the results.
Note: This endpoint returns the same detailed category information as the search endpoint:
- Category identifiers (
id,uuid) - Hierarchical information (
parentId,pathIds,path,childrenIds) - Attribute set association (
attributeSetId) - Visibility and status flags (
visible,fulfillmentVisible,qcDisabled,serialNumberRequired,status)
Important:
- The
ids[]parameter is required and accepts an array of category IDs - The
limitandoffsetparameters are required for pagination - Maximum
limitvalue depends on your system configuration (typically 100) - Use this endpoint when you have specific category IDs and need their details
- Categories with status
inactiveorinherited_inactiveshould not be used for new product assignments
Get Categories by UUIDs
GET /v2/categories/uuids
Summary: Get the categories for the provided uuids.
Description: This endpoint allows you to retrieve specific categories by providing their UUIDs. This is useful when you already know the category UUIDs and need to fetch their details in bulk, rather than searching or paginating through all categories.
The endpoint supports pagination through the limit and offset parameters, and the includeInaccessible parameter to control whether restricted categories are included in the results.
Note: This endpoint returns the same detailed category information as the search endpoint:
- Category identifiers (
id,uuid) - Hierarchical information (
parentId,pathIds,path,childrenIds) - Attribute set association (
attributeSetId) - Visibility and status flags (
visible,fulfillmentVisible,qcDisabled,serialNumberRequired,status)
Important:
- The
uuids[]parameter is required and accepts an array of category UUIDs (strings) - The
limitandoffsetparameters are required for pagination - Maximum
limitvalue depends on your system configuration (typically 100) - Use this endpoint when you have specific category UUIDs and need their details
- Categories with status
inactiveorinherited_inactiveshould not be used for new product assignments
Get Category Attributes
GET /v2/category/{categoryId}/attributes
Summary: Get category attributes
Description: Return category attributes. In SellerCenter you can sell products in different categories. Every product set has attributes ("colour", "warranty period", "fabric", etc). Not every attribute is applicable to every category. In order to make creation of products easier we are using only relevant for each category attributes. To do that each category has so called AttributeSet. AttributeSet is a way to group attributes. Returns attributes for inactive category also, but not for deleted one.
For example, products in categories "Men classic shoes" and "Golden Rings" will have different attributes therefore category "Men classic shoes" will have AttributeSet "Shoes" and category "Golden Rings" will have AttributeSet "Jewelry".
Each Attribute belongs to one AttributeSet. For example attribute "Material of soil" will belong to AttributeSet "Shoes" and "Probe of Gold" will belong to AttributeSet "Jewelry".
Some Attributes are "global", which means that they belong to any category and common for all products. Example of global attributes: "Warranty period", "Country of Origin" and so on.
When you want to create product in certain category you need to get list of attributes for this category and this is what this endpoint is for.
Please, carefully read description of each field in the model and make sure to unfold description of every child objects (especially "options")
Get Category Automatic Nomenclature
GET /v2/category/{categoryId}/automatic-nomenclature
Summary: Returns formula for calculating automatic nomenclature.
Description: This endpoint may be used when you implement UI for SellerCenter operations. For some categories there is so called "Automatic Nomenclature" feature enabled. If it is configured, then name of product set get calculated automatically based on some other attributes.
For example when this endpoint returns "attr.brand attr.model attr.color", then provided name of product set will be ignored during saving and name will be set to "Levis 501 Blue".
This endpoint may be used interactively show to user in UI what will be resulted name of product set.
If empty string is returned then no formula is applied. Additionally, empty string (no formula) will be returned when you request it for inactive and/or deleted categories or categories outside of category root for current seller.
As user of this endpoint to calculate name of product set you need to replace all occurances of attr.[a-zA-Z0-9] with values of attributes with given names.
Example: you got following string as response "attr.brand attr.model (attr.color)". You need to go through attributes of current product set and find attributes with names equal to brand, model and color. Then you do replacement in initial string so that attr.brand will be replaced with Adidas. So at the end you will have resulted name for your product set as Adidas 4DFWD (Orange). Also, note that in formula the could be string characters like ( and ) in given example, you don't need to replace them with anything.
Get Category Children
GET /v2/category/{categoryId}/children
Summary: Get category's direct children
Description: Return category 1st level/direct children.
Get Category Most Popular Sizes
GET /v2/category/{categoryId}/most-popular-sizes
Summary: Get most popular size ranking for a category
Description: Return most popular size based on each category-size system combination.
Get Category Settings
GET /v2/category/{categoryId}/settings
Summary: Get category settings
Description: Return category settings. In SellerCenter you can setup image or price restrictions for every category. The settings can be inherited from the parent category.
Get Category Mappings
GET /v2/category/mappings
Summary: Get the all category-to-attribute mapping information.
Description: Depending on selected category, available options in some attributes can be limited. For example, there is an attribute "Season" with typical values like "Summer", "Autumn", "Winter" etc. In category "Winter sport clothing" options for attribute "Season" can be limited to only "Winter". If you will try to create or update product set in this category with Season=Summer there will be a validation error.
When you request attributes for certain category using GET /v2/category/{categoryId}/attributes, this mapping is already included. That means when you request GET /v2/category/{category Id of Winter sport clothing}/attributes then in available options of attribute "Season" you will see only "Winter".
Get Most Used Categories
GET /v2/category/most-used
Summary: Get most used categories
Description: Return most used categories
Get Root Category
GET /v2/category/root
Summary: Get root category
Description: Return root category
Get Category Tree
GET /v2/category/tree
Summary: Get categories tree
Description: Return Category tree for active categories only