Overview
The Categories API allows you to organize products in a hierarchical structure. Each category can contain multiple subcategories, providing a flexible taxonomy for your product catalog.
The Category Object
Unique identifier for the category (UUID)
Category name (max 100 characters, must be unique)
Array of subcategory objects associated with this category
Object containing count of related entities (e.g., total subcategories)
Category creation timestamp
List Categories
curl -X GET "https://api.beils.com/api/catalog/categories" \
-H "Authorization: Bearer YOUR_TOKEN"
Response
Returns an array of category objects, ordered alphabetically by name. Each category includes up to 4 subcategories for preview and a count of total subcategories.
[
{
"category_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Hair Care",
"description": "Products for hair treatment and styling",
"subcategories": [
{
"subcategory_id": "660e8400-e29b-41d4-a716-446655440001",
"name": "Shampoos"
},
{
"subcategory_id": "660e8400-e29b-41d4-a716-446655440002",
"name": "Conditioners"
},
{
"subcategory_id": "660e8400-e29b-41d4-a716-446655440003",
"name": "Hair Masks"
}
],
"_count": {
"subcategories": 8
},
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T10:30:00Z"
},
{
"category_id": "770e8400-e29b-41d4-a716-446655440004",
"name": "Skin Care",
"description": "Products for facial and body skin care",
"subcategories": [
{
"subcategory_id": "880e8400-e29b-41d4-a716-446655440005",
"name": "Cleansers"
},
{
"subcategory_id": "880e8400-e29b-41d4-a716-446655440006",
"name": "Moisturizers"
}
],
"_count": {
"subcategories": 6
},
"created_at": "2024-03-14T14:20:00Z",
"updated_at": "2024-03-14T14:20:00Z"
}
]
Create Category
curl -X POST "https://api.beils.com/api/catalog/categories" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Hair Care",
"description": "Products for hair treatment and styling",
"subcategories": ["Shampoos", "Conditioners", "Hair Masks"]
}'
Body Parameters
Category name (max 100 characters, must be unique)
Array of subcategory names (strings) to create under this category
Response
Returns the created category object.
{
"category_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Hair Care",
"description": "Products for hair treatment and styling",
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T10:30:00Z"
}
Error Responses
El nombre de la categoría es obligatorio
Ya existe una categoría con este nombre
Error interno del servidor
Update Category
curl -X PUT "https://api.beils.com/api/catalog/categories/{category_id}" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Hair Care Products",
"description": "Professional hair treatment and styling products",
"subcategories": ["Shampoos", "Conditioners", "Hair Masks", "Styling Gels"]
}'
Path Parameters
The unique category identifier
Body Parameters
Category name (must be unique)
Complete array of subcategory names. The system will:
- Create new subcategories not currently in the category
- Delete subcategories not included in the array
- Keep existing subcategories that are still in the array
When updating subcategories, provide the complete list of subcategory names you want to keep. Any subcategories not in the list will be removed.
Response
Returns the updated category object.
Error Responses
Error interno del servidor
Delete Category
curl -X DELETE "https://api.beils.com/api/catalog/categories/{category_id}" \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
The unique category identifier
Response
Error Responses
Error interno del servidor
Deleting a category will cascade delete all its subcategories. Products associated with this category will have their category_id set to null but will not be deleted.
Working with Subcategories
Subcategory Structure
Subcategories are automatically created when you include them in the subcategories array during category creation or update. Each subcategory must have a unique name within its parent category.
Subcategory Object
Unique identifier for the subcategory (UUID)
Subcategory name (max 100 characters)
Managing Subcategories
For advanced subcategory management (direct CRUD operations on subcategories), see the Subcategories API documentation.
Use Cases
Product Organization
Categories and subcategories help organize your product catalog:
{
"category": "Hair Care",
"subcategories": [
"Shampoos",
"Conditioners",
"Hair Masks",
"Styling Products",
"Hair Color"
]
}
Filtering Products
Use category IDs to filter products in the Products API:
curl -X GET "https://api.beils.com/api/catalog/products?category_id={category_id}"
Multi-level Navigation
Build hierarchical navigation menus using categories and their subcategories for improved user experience in your beauty center’s e-commerce or POS system.