Admin Categories API — Manage Product Categories

The Admin Categories API lets you build and maintain the taxonomy that organizes your product catalog. Use it to create categories, control their visibility with the is_active flag, assign products to categories, and soft-delete categories when they are no longer needed. Unlike the public catalog endpoint, the admin view surfaces inactive and optionally deleted categories so you have full visibility into every state.

All category endpoints require an authenticated session with the ADMIN or SUPER_ADMIN role. Fetch a CSRF token from GET /auth/csrf-token and pass it in the x-csrf-token header for every POST, PATCH, PUT, and DELETE request.

Retrieve a paginated list of categories from the admin view. Unlike the public endpoint, inactive and soft-deleted categories are visible here depending on the filter flags you provide.

GET /admin/categories

Query Parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Items per page. Accepted range: 1–100.

string

Free-text search across category name and description.

string

default:"name"

Sort field. Prefix with - for descending. Accepted values: name, -name, created_at, -created_at, updated_at, -updated_at.

string

Filter by active status. Pass "true" to return only active categories, "false" for inactive only. Omit to return all.

string

default:"false"

Pass "true" to include soft-deleted categories. Must be the string "true" or "false".

Response

array

Array of category objects.

Show Category fields

string

Category public ID, prefixed cat_.

string

Display name.

string

URL-safe slug.

string | null

Category description, or null.

boolean

Whether the category is visible to customers.

string | null

ISO 8601 UTC soft-deletion timestamp, or null if the category is not deleted.

string

ISO 8601 UTC creation timestamp.

string

ISO 8601 UTC last-updated timestamp.

object

Show Pagination fields

integer

Total matching records.

integer

Total number of pages.

boolean

Whether a next page exists.

boolean

Whether a previous page exists.

Create Category

Create a new product category. Only name is required. The API auto-generates a URL slug from the name if you do not supply one.

POST /admin/categories

Request Body

string

required

Category display name. Between 1 and 255 characters.

string

URL-safe slug. Must match ^[a-z0-9]+(?:-[a-z0-9]+)*$ and be unique. Auto-generated from name if omitted. Maximum 255 characters.

string

Long-form category description. Maximum 10,000 characters. Optional.

boolean

default:"true"

Whether the category is immediately visible to customers. Defaults to true.

When you omit slug, the API derives it from the name by lowercasing, replacing spaces with hyphens, and stripping unsupported characters. For example, "Running Shoes" becomes "running-shoes". If the auto-generated slug conflicts with an existing one, the API appends a short unique suffix automatically. Provide an explicit slug when you need deterministic URLs.

Example

# Step 1: get CSRF token
TOKEN=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" \
  | jq -r '.data.csrf_token')

# Step 2: create category
curl -X POST https://api.example.com/api/v1/admin/categories \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "name": "Sneakers",
    "slug": "sneakers",
    "description": "Athletic and casual footwear for everyday wear.",
    "is_active": true
  }'

const response = await fetch('https://api.example.com/api/v1/admin/categories', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'x-csrf-token': csrfToken,
  },
  body: JSON.stringify({
    name: 'Sneakers',
    slug: 'sneakers',
    description: 'Athletic and casual footwear for everyday wear.',
    is_active: true,
  }),
});
const data = await response.json();

201 Response

{
  "success": true,
  "data": {
    "public_id": "cat_01H",
    "name": "Sneakers",
    "slug": "sneakers",
    "description": "Athletic and casual footwear for everyday wear.",
    "is_active": true,
    "deleted_at": null,
    "created_at": "2024-06-01T09:00:00.000Z",
    "updated_at": "2024-06-01T09:00:00.000Z"
  }
}

Error Responses

Status	Meaning
`400`	Validation error — invalid slug format or missing required field.
`401`	No active session.
`403`	Insufficient role.
`409`	A category with the given slug already exists.

Get Category

Fetch the full admin projection of a single category by its public ID. The admin view returns the category regardless of is_active or soft-deletion state.

GET /admin/categories/{category_public_id}

Path Parameters

string

required

The category’s public ID, prefixed cat_.

Returns the full category object. Responds with 404 if the category does not exist.

Update Category

Partially update a category’s fields. Only the fields you supply are changed. Pass null for description to explicitly clear it.

PATCH /admin/categories/{category_public_id}

Path Parameters

string

required

The category’s public ID, prefixed cat_.

Request Body

At least one field is required.

string

Updated display name. Between 1 and 255 characters.

string

Updated URL slug. Must match ^[a-z0-9]+(?:-[a-z0-9]+)*$. Returns 409 on conflict.

string | null

Updated description. Pass null to clear the existing value.

boolean

Toggle customer visibility without deleting the category.

Use is_active: false to temporarily hide a category from customers — for example, while you reorganize its products or prepare a seasonal launch — without soft-deleting it. Toggle it back to true when you are ready to go live. This is much easier to reverse than a delete operation.

Example

curl -X PATCH https://api.example.com/api/v1/admin/categories/cat_01H \
  -H "Content-Type: application/json" \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN" \
  -d '{
    "name": "Sneakers & Training",
    "is_active": false
  }'

await fetch('https://api.example.com/api/v1/admin/categories/cat_01H', {
  method: 'PATCH',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'x-csrf-token': csrfToken,
  },
  body: JSON.stringify({ name: 'Sneakers & Training', is_active: false }),
});

Delete Category

Soft-delete a category. The category is immediately hidden from all customer-facing endpoints but retained in the database for referential integrity. Returns 204 No Content on success.

DELETE /admin/categories/{category_public_id}

Path Parameters

string

required

The category’s public ID, prefixed cat_.

Example

curl -X DELETE https://api.example.com/api/v1/admin/categories/cat_01H \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN"

await fetch('https://api.example.com/api/v1/admin/categories/cat_01H', {
  method: 'DELETE',
  credentials: 'include',
  headers: { 'x-csrf-token': csrfToken },
});

Error Responses

Status	Meaning
`401`	No active session.
`403`	Insufficient role.
`404`	Category not found.

Assign Product to Category

Assign a single product to a category. The operation is idempotent — assigning a product that is already in the category returns 204 without error.

PUT /admin/categories/{category_public_id}/products/{product_public_id}

Path Parameters

string

required

The category’s public ID, prefixed cat_.

string

required

The product’s public ID, prefixed prd_.

Example

curl -X PUT \
  https://api.example.com/api/v1/admin/categories/cat_01H/products/prd_01H \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN"

await fetch(
  'https://api.example.com/api/v1/admin/categories/cat_01H/products/prd_01H',
  {
    method: 'PUT',
    credentials: 'include',
    headers: {
      'x-csrf-token': csrfToken,
    },
  }
);

Response

Returns 204 No Content on success. Returns 404 if the category or product does not exist.

Remove Product from Category

Unassign a single product from a category. The operation succeeds with 204 even if the product was not assigned to the category. Returns 404 if the category or product does not exist.

DELETE /admin/categories/{category_public_id}/products/{product_public_id}

Path Parameters

string

required

The category’s public ID, prefixed cat_.

string

required

The product’s public ID, prefixed prd_.

Example

curl -X DELETE \
  https://api.example.com/api/v1/admin/categories/cat_01H/products/prd_01H \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $TOKEN"

await fetch(
  'https://api.example.com/api/v1/admin/categories/cat_01H/products/prd_01H',
  {
    method: 'DELETE',
    credentials: 'include',
    headers: { 'x-csrf-token': csrfToken },
  }
);

Error Responses

Status	Meaning
`401`	No active session.
`403`	Insufficient role.
`404`	Category or product not found.

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Categories API — Manage Product Categories

Query Parameters

Response

Create Category

Request Body

Example

201 Response

Error Responses

Get Category

Path Parameters

Update Category

Path Parameters

Request Body

Example

Delete Category

Path Parameters

Example

Error Responses

Assign Product to Category

Path Parameters

Example

Response

Remove Product from Category

Path Parameters

Example

Error Responses

​List Categories

​Query Parameters

​Response

​Create Category

​Request Body

​Example

​201 Response

​Error Responses

​Get Category

​Path Parameters

​Update Category

​Path Parameters

​Request Body

​Example

​Delete Category

​Path Parameters

​Example

​Error Responses

​Assign Product to Category

​Path Parameters

​Example

​Response

​Remove Product from Category

​Path Parameters

​Example

​Error Responses

List Categories

Query Parameters

Response

Create Category

Request Body

Example

201 Response

Error Responses

Get Category

Path Parameters

Update Category

Path Parameters

Request Body

Example

Delete Category

Path Parameters

Example

Error Responses

Assign Product to Category

Path Parameters

Example

Response

Remove Product from Category

Path Parameters

Example

Error Responses