Skip to main content
GET
/
api
/
catalog
/
subcategories
Subcategories
curl --request GET \
  --url https://api.example.com/api/catalog/subcategories
{
  "subcategory_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "category_id": "<string>",
  "category": {
    "name": "<string>"
  },
  "created_at": "<string>",
  "updated_at": "<string>"
}

​
Overview

Subcategories allow you to organize products into more specific classifications within parent categories. Each subcategory must belong to a parent category, and the combination of name and category must be unique.

​
Authentication

All subcategory endpoints require authentication. Include a valid session token in your request.

​
List Subcategories

Retrieves all subcategories with their parent category information, ordered alphabetically by name.

​
Response

​
subcategory_id
string
Unique identifier (UUID) for the subcategory
​
name
string
Name of the subcategory
​
description
string
Optional description of the subcategory
​
category_id
string
ID of the parent category
​
category
object
Parent category information
​
created_at
string
Creation timestamp
​
updated_at
string
Last update timestamp

​
Example Request

curl -X GET "https://api.example.com/api/catalog/subcategories" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  {
    "subcategory_id": "abc123",
    "name": "Cremas faciales",
    "description": "Cremas y tratamientos para el rostro",
    "category_id": "cat456",
    "category": {
      "name": "Cosméticos"
    },
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

​
Create Subcategory

Creates a new subcategory within a parent category.

​
Request Body

​
name
string
required
Name of the subcategory (must be unique within the parent category)
​
category_id
string
required
ID of the parent category
​
description
string
Optional description of the subcategory

​
Response

Returns the created subcategory object with parent category information.

​
Example Request

curl -X POST "https://api.example.com/api/catalog/subcategories" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cremas faciales",
    "description": "Cremas y tratamientos para el rostro",
    "category_id": "cat456"
  }'

​
Error Responses

  • 400: Name and category_id are required
  • 409: A subcategory with this name already exists in this category
  • 500: Internal server error

​
Update Subcategory

Updates an existing subcategory’s information.

​
Path Parameters

​
id
string
required
The unique identifier of the subcategory to update

​
Request Body

​
name
string
New name for the subcategory
​
description
string
New description
​
category_id
string
New parent category ID (to move the subcategory)

​
Response

Returns the updated subcategory object with parent category information.

​
Example Request

curl -X PUT "https://api.example.com/api/catalog/subcategories/abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cremas faciales premium",
    "description": "Cremas de alta gama para tratamiento facial"
  }'

​
Error Responses

  • 400: ID required
  • 404: Subcategory not found
  • 409: Name already registered in this category
  • 500: Internal server error

​
Delete Subcategory

Deletes a subcategory. Note that this will fail if products are associated with this subcategory.

​
Path Parameters

​
id
string
required
The unique identifier of the subcategory to delete

​
Response

Returns the deleted subcategory object.

​
Example Request

curl -X DELETE "https://api.example.com/api/catalog/subcategories/abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Error Responses

  • 400: ID required
  • 404: Subcategory not found
  • 409: Cannot delete subcategory with associated products
  • 500: Internal server error
Deleting a subcategory will fail if there are products assigned to it. Reassign or delete those products first.

Categories

Manage parent categories

Products

Manage products assigned to subcategories

Build docs developers (and LLMs) love

Get started for freeTalk to us