Skip to main content

​
Overview

The Products API allows you to manage your product catalog, including inventory tracking, pricing, categorization, and brand associations. Products can be organized using categories, subcategories, brands, and tags.

​
The Product Object

​
product_id
string
required
Unique identifier for the product (UUID)
​
name
string
required
Product name (max 150 characters)
​
description
string
Detailed product description
​
sku
string
Stock Keeping Unit - unique product identifier (max 50 characters)
​
barcode
string
Product barcode (max 50 characters)
​
price
number
required
Product price
​
tax_rate
number
Tax rate percentage (default: 21.0)
​
stock
integer
Current stock quantity (default: 0)
​
min_stock
integer
Minimum stock threshold for alerts (default: 0)
​
image_url
string
URL to product image (max 255 characters)
​
status
string
Product status: activo or inactivo (default: activo)
​
brand_id
string
Associated brand ID (UUID)
​
category_id
string
Associated category ID (UUID)
​
subcategory_id
string
Associated subcategory ID (UUID)
​
brand
object
Populated brand object with name field
​
category
object
Populated category object with name field
​
subcategory
object
Populated subcategory object with name field
​
tags
array
Array of associated tags with tag_id and name fields
​
created_at
datetime
Product creation timestamp
​
updated_at
datetime
Last update timestamp

​
List Products

curl -X GET "https://api.beils.com/api/catalog/products" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieves a list of all products with their associated brand, category, subcategory, and tags.

​
Query Parameters

​
category_id
string
Filter products by category ID
​
subcategory_id
string
Filter products by subcategory ID
​
brand_id
string
Filter products by brand ID
​
search
string
Search products by name, description, SKU, or barcode (partial match)

​
Response

Returns an array of product objects, ordered by creation date (newest first). 
[
  {
    "product_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Professional Shampoo 500ml",
    "description": "Moisturizing shampoo for all hair types",
    "sku": "SHA-500-001",
    "barcode": "8436535240012",
    "price": 24.99,
    "tax_rate": 21.0,
    "stock": 45,
    "min_stock": 10,
    "image_url": "https://cdn.beils.com/products/shampoo-001.jpg",
    "status": "activo",
    "brand_id": "brand_123",
    "category_id": "cat_456",
    "subcategory_id": "subcat_789",
    "brand": { "name": "Premium Hair Care" },
    "category": { "name": "Hair Products" },
    "subcategory": { "name": "Shampoos" },
    "tags": [
      { "tag_id": "tag_1", "name": "organic" },
      { "tag_id": "tag_2", "name": "sulfate-free" }
    ],
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2024-03-15T10:30:00Z"
  }
]

​
Create Product

curl -X POST "https://api.beils.com/api/catalog/products" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional Shampoo 500ml",
    "description": "Moisturizing shampoo for all hair types",
    "sku": "SHA-500-001",
    "barcode": "8436535240012",
    "price": 24.99,
    "tax_rate": 21.0,
    "stock": 50,
    "min_stock": 10,
    "status": "activo",
    "brand_id": "brand_123",
    "category_id": "cat_456",
    "subcategory_id": "subcat_789",
    "tags": ["tag_1", "tag_2"]
  }'
Creates a new product in the catalog.

​
Body Parameters

​
name
string
required
Product name (max 150 characters)
​
description
string
Product description
​
sku
string
Unique SKU (max 50 characters)
​
barcode
string
Product barcode (max 50 characters)
​
price
number
required
Product price
​
tax_rate
number
Tax rate percentage (default: 21.0)
​
stock
integer
Initial stock quantity (default: 0)
​
min_stock
integer
Minimum stock threshold (default: 0)
​
image_url
string
URL to product image
​
status
string
Product status: activo or inactivo
​
brand_id
string
Brand ID to associate with product
​
category_id
string
Category ID to associate with product
​
subcategory_id
string
Subcategory ID to associate with product
​
tags
array
Array of tag IDs to associate with product

​
Response

Returns the created product object with populated relations.

​
Get Product

curl -X GET "https://api.beils.com/api/catalog/products/{product_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieves a specific product by ID with all related data.

​
Path Parameters

​
product_id
string
required
The unique product identifier

​
Response

Returns the product object with full brand, category, subcategory, and tags details.

​
Error Responses

​
400
error
Product ID is required
​
404
error
Product not found

​
Update Product

curl -X PUT "https://api.beils.com/api/catalog/products/{product_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional Shampoo 500ml - Updated",
    "price": 26.99,
    "stock": 55,
    "tags": ["tag_1", "tag_3"]
  }'
Updates an existing product. Only provided fields will be updated.

​
Path Parameters

​
product_id
string
required
The unique product identifier

​
Body Parameters

All fields are optional. Only include the fields you want to update.
​
name
string
Product name
​
description
string
Product description
​
sku
string
Product SKU
​
barcode
string
Product barcode
​
price
number
Product price
​
tax_rate
number
Tax rate percentage
​
stock
integer
Stock quantity
​
min_stock
integer
Minimum stock threshold
​
image_url
string
Product image URL
​
status
string
Product status
​
brand_id
string
Brand ID (use empty string or null to remove association)
​
category_id
string
Category ID (use empty string or null to remove association)
​
subcategory_id
string
Subcategory ID (use empty string or null to remove association)
​
tags
array
Array of tag IDs to associate. This replaces all existing tags.
When updating tags, the existing tag associations are completely replaced with the new array. To remove all tags, pass an empty array [].

​
Response

Returns the updated product object with populated relations.

​
Delete Product

curl -X DELETE "https://api.beils.com/api/catalog/products/{product_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"
Deletes a product from the catalog. This also removes all associated tag relationships.

​
Path Parameters

​
product_id
string
required
The unique product identifier

​
Response

{
  "success": true
}
Deleting a product will remove it from any packs it’s associated with. Make sure to review pack contents before deleting products.

Build docs developers (and LLMs) love

Get started for freeTalk to us