---
title: "Categories Management"
canonical: "https://red-ant-documentation.refined.site/space/RDD/1361313806/Categories%20Management"
format: markdown
---
> Macro (toc)

## Summary

The Category API behaves as a standard resource, with the actions to support the management of categories and their hierarchical relationships. 

## API Reference

[https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories](https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories) 

## Category Structure

Categories in RetailOS are organized hierarchically using a `parentId` field. A category can either be a top-level category (if `parentId` is `NULL`) or a subcategory nested under a parent category (if parentId is NOT `NULL`). This structure enables dynamic nesting and allows a clear categorization of a given product.   
  
**Example (other attributes obscured for brevity):**

## Category Schema

[https://redantdigital.atlassian.net/wiki/spaces/RDD/pages/718766103](https://redantdigital.atlassian.net/wiki/spaces/RDD/pages/718766103) 

## Creating Categories

***URL:*** `POST /v2/categories`

***Summary***: Creates a new category

***Reference: ***[https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories/post_categories](https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories/post_categories) 

***Example CURL:***

```
curl -X POST "https://example-api.com/v2/categories" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bag",
    "externalCategoryId": "bag_category",
    "image": "https://example.com/example-bag-image.jpg",
    "parentId": "<UUID>",
    "order": 1,
    "updateSource": "RetailOS"
  }'
```

**Required Attributes:**

- name
- updateSource

**API Responses**

- `200 OK`: Category created successfully.
- `400 Bad Request`: Invalid request body.
- `409 Conflict`: Category already exists.

## Updating Categories

***URL:*** `PATCH /v2/categories/{id}`

***Summary***: Updates an existing category by ID

***Reference: ***[https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories/patch_categories__id_](https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories/patch_categories__id_) 

***Example CURL:***

```
curl -X PATCH "https://example-api.com/v2/categories/1234" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-category-updated",
    "externalCategoryId": "test_category",
    "image": "https://example.com/example-image_v2.jpg",
    "order": 2,
    "updateSource": "RetailOS"
  }'
```

**Required Attributes:**

- updateSource

**API Responses**

- `200 OK`: Category updated successfully.
- `400 Bad Request`: Invalid request body.
- `404 Not Found`: Category not found.

## Deleting Categories

***URL:*** `PATCH /v2/categories/{id}`

***Summary***: Deletes an existing category by ID

***Reference and examples: ***[https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories/patch_categories__id_](https://digital-store-api-qa.redant.cloud/v2/docs/#/Categories/patch_categories__id_) 

***Example CURL:***

```
curl -X PATCH "https://example-api.com/v2/categories/1234" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deletedAt": "2024-11-26T13:22:00.522Z",
    "updateSource": "RetailOS"
  }'
```

**Required Attributes:**

- deletedAt
- updateSource

**API Responses**

- `200 OK`: Category updated/deleted successfully.
- `400 Bad Request`: Invalid request body.
- `404 Not Found`: Category not found.