> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.oryxa.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Organize Products with Categories and Brands

> Create hierarchical product categories and brand records in Synq. Then associate products with them to power navigation, filtering, and brand pages.

Synq gives you two independent taxonomy systems for organizing your catalog: **categories** and **brands**. Categories are hierarchical — you can nest them to any depth using a `parentId` — and are ideal for powering storefront navigation trees, faceted search filters, and merchandising rules. Brands represent the manufacturer or label behind a product, complete with a logo URL, and are scoped per tenant so each of your clients maintains their own brand registry. Both resources live under the `/api/v1/pim` prefix and follow the same create-and-list pattern.

<Note>
  All requests require the standard headers:
  `Authorization: Bearer <token>`, `X-Tenant-ID`, and `X-Org-ID`.
</Note>

***

## Categories

### List categories

Retrieve all active categories for your tenant, ordered alphabetically by name.

```bash theme={null}
GET /api/v1/pim/categories
```

```bash theme={null}
curl https://api.synq.com/api/v1/pim/categories \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID"
```

**Response** `200 OK`

```json theme={null}
[
  {
    "id": "a1b2c3d4-0001-7890-abcd-ef1234567890",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "parent_id": null,
    "name": "Clothing",
    "slug": "clothing",
    "description": "All apparel and wearable goods.",
    "created_at": "2024-10-01T09:00:00Z",
    "updated_at": "2024-10-01T09:00:00Z"
  },
  {
    "id": "a1b2c3d4-0002-7890-abcd-ef1234567890",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "parent_id": "a1b2c3d4-0001-7890-abcd-ef1234567890",
    "name": "Knitwear",
    "slug": "knitwear",
    "description": "Sweaters, cardigans, and knit accessories.",
    "created_at": "2024-10-01T09:05:00Z",
    "updated_at": "2024-10-01T09:05:00Z"
  }
]
```

<ResponseField name="parent_id" type="string | null">
  UUID of the parent category, or `null` for top-level categories. Use this to reconstruct the tree client-side.
</ResponseField>

<ResponseField name="slug" type="string">
  A URL-safe identifier for this category (e.g., `knitwear`). Must be unique within your tenant.
</ResponseField>

***

### Create a category

```bash theme={null}
POST /api/v1/pim/categories
```

**Request body**

<ParamField body="name" type="string" required>
  Display name for the category (e.g., `"Knitwear"`).
</ParamField>

<ParamField body="slug" type="string" required>
  URL-safe unique identifier (e.g., `"knitwear"`). Lowercase letters, numbers, and hyphens only.
</ParamField>

<ParamField body="description" type="string">
  A short description of what belongs in this category.
</ParamField>

<ParamField body="parentId" type="string">
  UUID of the parent category. Omit or leave empty to create a root-level category.
</ParamField>

<CodeGroup>
  ```bash Root category theme={null}
  curl -X POST https://api.synq.com/api/v1/pim/categories \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-ID: $TENANT_ID" \
    -H "X-Org-ID: $ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Clothing",
      "slug": "clothing",
      "description": "All apparel and wearable goods."
    }'
  ```

  ```bash Child category theme={null}
  curl -X POST https://api.synq.com/api/v1/pim/categories \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-ID: $TENANT_ID" \
    -H "X-Org-ID: $ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Knitwear",
      "slug": "knitwear",
      "description": "Sweaters, cardigans, and knit accessories.",
      "parentId": "a1b2c3d4-0001-7890-abcd-ef1234567890"
    }'
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "id": "a1b2c3d4-0002-7890-abcd-ef1234567890",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "parent_id": "a1b2c3d4-0001-7890-abcd-ef1234567890",
  "name": "Knitwear",
  "slug": "knitwear",
  "description": "Sweaters, cardigans, and knit accessories.",
  "created_at": "2024-11-15T12:00:00Z",
  "updated_at": "2024-11-15T12:00:00Z"
}
```

***

## Brands

### List brands

Retrieve all active brands for your tenant, ordered alphabetically by name.

```bash theme={null}
GET /api/v1/pim/brands
```

```bash theme={null}
curl https://api.synq.com/api/v1/pim/brands \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID"
```

**Response** `200 OK`

```json theme={null}
[
  {
    "id": "b1b2c3d4-0001-7890-abcd-ef1234567890",
    "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "name": "NordicThread",
    "description": "Scandinavian-inspired knitwear and outerwear.",
    "logo_url": "https://cdn.example.com/brands/nordicthread-logo.svg",
    "created_at": "2024-10-01T09:00:00Z",
    "updated_at": "2024-10-01T09:00:00Z"
  }
]
```

***

### Create a brand

```bash theme={null}
POST /api/v1/pim/brands
```

**Request body**

<ParamField body="name" type="string" required>
  The brand's display name (e.g., `"NordicThread"`).
</ParamField>

<ParamField body="description" type="string">
  A short description of the brand's identity or product range.
</ParamField>

<ParamField body="logoUrl" type="string">
  A fully qualified URL to the brand's logo image.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.com/api/v1/pim/brands \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-ID: $TENANT_ID" \
    -H "X-Org-ID: $ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "NordicThread",
      "description": "Scandinavian-inspired knitwear and outerwear.",
      "logoUrl": "https://cdn.example.com/brands/nordicthread-logo.svg"
    }'
  ```

  ```json Request body theme={null}
  {
    "name": "NordicThread",
    "description": "Scandinavian-inspired knitwear and outerwear.",
    "logoUrl": "https://cdn.example.com/brands/nordicthread-logo.svg"
  }
  ```
</CodeGroup>

**Response** `200 OK`

```json theme={null}
{
  "id": "b1b2c3d4-0001-7890-abcd-ef1234567890",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "name": "NordicThread",
  "description": "Scandinavian-inspired knitwear and outerwear.",
  "logo_url": "https://cdn.example.com/brands/nordicthread-logo.svg",
  "created_at": "2024-11-15T12:30:00Z",
  "updated_at": "2024-11-15T12:30:00Z"
}
```

<ResponseField name="logo_url" type="string">
  The stored URL of the brand's logo. Note that the request field is `logoUrl` (camelCase) and the response field is `logo_url` (snake\_case).
</ResponseField>

***

## Associate a product with a category or brand

When you create or update a product, pass the `category` field as a free-text label. To associate a product with a structured category or brand record using their UUIDs, include `category_id` and `brand_id` in your update payload.

```bash theme={null}
PUT /api/v1/pim/products/{id}
```

```json theme={null}
{
  "title": "Merino Wool Crew Neck Sweater",
  "category": "Knitwear"
}
```

<Tip>
  The `category` (text) and `category_id` (UUID reference) fields coexist on the product. Using `category_id` links to a structured category record and is preferred when you need to power hierarchical navigation or merchandising rules. The `category` text field is useful for quick imports where full taxonomy isn't yet defined.
</Tip>

<Warning>
  Deleting a category or brand does not cascade to products. Products that reference a deleted category or brand by ID will retain the stale reference. Audit and re-associate products before removing taxonomy records.
</Warning>