Overview
The Brands API allows you to manage product brands in your catalog. Brands can be associated with products to help organize inventory and provide filtering capabilities.
The Brand Object
Unique identifier for the brand (UUID)
Brand name (max 100 characters, must be unique)
List Brands
curl -X GET "https://api.beils.com/api/catalog/brands" \
-H "Authorization: Bearer YOUR_TOKEN"
Response
Returns an array of brand objects, ordered alphabetically by name.
[
{
"brand_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Premium Hair Care",
"description": "Professional hair care products for salons",
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T10:30:00Z"
},
{
"brand_id": "660e8400-e29b-41d4-a716-446655440001",
"name": "Natural Beauty",
"description": "Organic and natural beauty products",
"created_at": "2024-03-14T14:20:00Z",
"updated_at": "2024-03-14T14:20:00Z"
},
{
"brand_id": "770e8400-e29b-41d4-a716-446655440002",
"name": "Luxury Skincare",
"description": "High-end skincare and anti-aging products",
"created_at": "2024-03-13T09:15:00Z",
"updated_at": "2024-03-13T09:15:00Z"
}
]
Create Brand
curl -X POST "https://api.beils.com/api/catalog/brands" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium Hair Care",
"description": "Professional hair care products for salons"
}'
Body Parameters
Brand name (max 100 characters, must be unique)
Response
Returns the created brand object wrapped in a brand property.
{
"brand": {
"brand_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Premium Hair Care",
"description": "Professional hair care products for salons",
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T10:30:00Z"
}
}
Error Responses
El nombre es obligatorio - or - Datos inválidos
Ya existe una marca con este nombre
Update Brand
curl -X PUT "https://api.beils.com/api/catalog/brands/{brand_id}" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium Hair Care Pro",
"description": "Professional hair care products for salons and spas"
}'
Path Parameters
The unique brand identifier
Body Parameters
Brand name (must be unique)
Response
Returns the updated brand object wrapped in a brand property.
{
"brand": {
"brand_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Premium Hair Care Pro",
"description": "Professional hair care products for salons and spas",
"created_at": "2024-03-15T10:30:00Z",
"updated_at": "2024-03-15T16:45:00Z"
}
}
Error Responses
ID requerido - or - Datos inválidos
Ya existe otra marca con este nombre
Delete Brand
curl -X DELETE "https://api.beils.com/api/catalog/brands/{brand_id}" \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
The unique brand identifier
Response
Error Responses
No se puede eliminar la marca porque tiene X producto(s) asociado(s).
Error al eliminar la marca
You cannot delete a brand that is associated with products. First, either delete the products or reassign them to a different brand.
Use Cases
Product Filtering
Use brand IDs to filter products in the Products API:
curl -X GET "https://api.beils.com/api/catalog/products?brand_id={brand_id}" \
-H "Authorization: Bearer YOUR_TOKEN"
Inventory Management
Organize your inventory by brand to:
- Track stock levels by brand
- Manage vendor relationships
- Create brand-specific promotions
- Generate brand performance reports
Product Association
When creating or updating products, associate them with a brand:
{
"name": "Professional Shampoo 500ml",
"brand_id": "550e8400-e29b-41d4-a716-446655440000",
"price": 24.99
}
{
"product_id": "...",
"name": "Professional Shampoo 500ml",
"brand_id": "550e8400-e29b-41d4-a716-446655440000",
"brand": {
"name": "Premium Hair Care"
},
"price": 24.99
}
Validation Rules
Name Uniqueness
Brand names must be unique across the system. When creating or updating a brand, the API validates that no other brand has the same name.
Product Dependencies
Before deleting a brand, the system checks for associated products. The API returns the count of associated products in the error message to help you understand the dependency.
The API uses Zod schema validation to ensure:
- Name is provided and is a non-empty string
- Description is optional but must be a string if provided
- Maximum length constraints are enforced
