Categories form the top level of the business hierarchy. Each category can contain sub-categories, which in turn group offers. Categories also define custom fields (including computed fields with formulas) that are inherited by all offers within the category. All categories support soft-delete (a deletedAt timestamp is set instead of permanent removal), version tracking (the version field auto-increments on every update), and audit logging (before/after snapshots are recorded for every CRUD operation).

See the Business Hierarchy feature page for UI guidance and conceptual overview.

Base path

/api/v1/categories        # Categories
/api/v1/sub-categories    # Sub-categories

Categories

GET /api/v1/categories

Returns a paginated list of categories for the current tenant, ordered by ordinal ascending. Each category includes its sub-categories with offer counts. By default, soft-deleted categories are excluded.

Query parameters

Parameter	Required	Type	Description
`limit`	No	integer	Maximum results per page. Default `25`.
`cursor`	No	string	Cursor for keyset pagination.
`includeDeleted`	No	string	Set to `"true"` to include soft-deleted categories in the results.

Response `200`

{
  "data": [
    {
      "id": "cat_01",
      "tenantId": "t_001",
      "name": "Acquisition",
      "description": "New customer acquisition offers.",
      "icon": "user-plus",
      "color": "blue",
      "status": "active",
      "ordinal": 0,
      "version": 1,
      "deletedAt": null,
      "customFields": [
        {
          "key": "base_rate",
          "label": "Base Rate",
          "type": "number",
          "defaultValue": 0
        },
        {
          "key": "personalized_rate",
          "label": "Personalized Rate",
          "type": "computed",
          "formula": "base_rate * (1 + customer.loyalty_score / 100)",
          "outputType": "number"
        }
      ],
      "subCategories": [
        {
          "id": "sub_01",
          "name": "Credit Cards",
          "_count": { "offers": 12 }
        }
      ],
      "createdAt": "2026-03-10T12:00:00.000Z",
      "updatedAt": "2026-03-12T09:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 4,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null
  }
}

Error codes

Code	Reason
`401`	Missing or invalid API key / session.
`403`	Insufficient role.

Create a category

POST /api/v1/categories

Request body

Field	Required	Type	Description
`name`	Yes	string (1-255)	Unique category name.
`description`	No	string	Category description.
`icon`	No	string	Icon identifier (e.g., Lucide icon name).
`color`	No	string	Display color. Default `"blue"`.
`status`	No	enum	`draft`, `active` (default), `paused`, `archived`.
`ordinal`	No	integer (>= 0)	Sort order. Default `0`.
`customFields`	No	array	Custom field definitions (see below). Max 500 items.

Custom field object

Field	Required	Type	Description
`key`	Yes	string	Machine-readable field key.
`label`	Yes	string	Human-readable label.
`type`	Yes	string	Field type: `text`, `number`, `boolean`, `select`, `computed`.
`defaultValue`	No	any	Default value for the field.
`formula`	Conditional	string	Formula expression. Required when `type` is `computed`.
`outputType`	Conditional	enum	`number` or `text`. Required when `type` is `computed`.

Computed fields require both a valid formula and an outputType (number or text). The formula is validated using the formula engine. Supported namespaces: fieldName (sibling fields), customer.* (enriched data), attributes.* (request-time attributes).

Example request

{
  "name": "Retention",
  "description": "Offers aimed at retaining existing customers.",
  "color": "green",
  "ordinal": 1,
  "customFields": [
    { "key": "discount_pct", "label": "Discount %", "type": "number", "defaultValue": 10 },
    {
      "key": "final_discount",
      "label": "Final Discount",
      "type": "computed",
      "formula": "discount_pct * (customer.tenure_years > 5 ? 1.2 : 1.0)",
      "outputType": "number"
    }
  ]
}

Response `201`

Returns the created category with version: 1, deletedAt: null, and sub-categories relation. An audit log entry is created with a create action and a snapshot of the new entity.

Error codes

Code	Reason
`400`	Validation error (missing name, invalid computed field).
`401`	Missing or invalid API key / session.
`403`	Insufficient role (requires `editor` or `admin`).
`409`	A category with that name already exists.
`415`	`Content-Type` is not `application/json`.

Update a category

PUT /api/v1/categories

Updates an existing category. Only provided fields are changed. The version field is auto-incremented and a before/after audit snapshot is recorded.

Request body

Field	Required	Type	Description
`id`	Yes	string	Category ID to update.

All other fields from the create schema are accepted as optional.

Response `200`

Returns the updated category object with the incremented version.

Error codes

Code	Reason
`400`	Validation error.
`401`	Missing or invalid API key / session.
`403`	Insufficient role.
`409`	A category with that name already exists.

Delete a category (soft-delete)

DELETE /api/v1/categories?id={categoryId}

Soft-deletes a category by setting its deletedAt timestamp. Cascade behavior: all child sub-categories and offers under this category are also soft-deleted. The version is incremented on the category and each cascaded child. An audit log entry is recorded for every affected entity.

Query parameters

Parameter	Required	Type	Description
`id`	Yes	string	Category ID to delete.

Response `200`

{
  "deleted": true,
  "id": "cat_01",
  "cascaded": 5,
  "message": "Category soft-deleted along with 5 child entities."
}

Error codes

Code	Reason
`400`	Missing `id` query parameter, entity not found, or entity already deleted.
`401`	Missing or invalid API key / session.
`403`	Insufficient role.

To restore a soft-deleted category, use POST /api/v1/restore?entityType=category&id={categoryId} (admin only). Restoring a category does not automatically restore cascaded children — you must restore sub-categories and offers individually.

Sub-categories

Sub-categories live under a category and group related offers. They also support soft-delete, version tracking, and audit logging.

List sub-categories

GET /api/v1/sub-categories

Query parameters

Parameter	Required	Type	Description
`categoryId`	No	string	Filter to a specific parent category.
`limit`	No	integer	Maximum results per page. Default `25`.
`cursor`	No	string	Cursor for keyset pagination.
`includeDeleted`	No	string	Set to `"true"` to include soft-deleted sub-categories.

Response `200`

{
  "data": [
    {
      "id": "sub_01",
      "tenantId": "t_001",
      "categoryId": "cat_01",
      "name": "Credit Cards",
      "description": "",
      "icon": "",
      "status": "active",
      "ordinal": 0,
      "version": 1,
      "deletedAt": null,
      "customFields": [],
      "category": { "id": "cat_01", "name": "Acquisition" },
      "_count": { "offers": 12 }
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null
  }
}

Create a sub-category

POST /api/v1/sub-categories

Request body

Field	Required	Type	Description
`categoryId`	Yes	string	Parent category ID.
`name`	Yes	string	Sub-category name.
`description`	No	string	Description.
`icon`	No	string	Icon identifier.
`status`	No	enum	`draft`, `active` (default), `paused`, `archived`.
`ordinal`	No	integer (>= 0)	Sort order. Default `0`.
`customFields`	No	array	Custom field definitions (same schema as categories).

Response `201`

Returns the created sub-category with its parent category relation, version: 1, and deletedAt: null.

Error codes

Code	Reason
`400`	Validation error (missing `categoryId` or `name`).
`401`	Missing or invalid API key / session.
`403`	Insufficient role.
`409`	A sub-category with that name already exists.
`415`	`Content-Type` is not `application/json`.

Update a sub-category

PUT /api/v1/sub-categories

Updates an existing sub-category. The version field is auto-incremented and a before/after audit snapshot is recorded.

Request body

Field	Required	Type	Description
`id`	Yes	string	Sub-category ID to update.

All other fields are optional.

Response `200`

Returns the updated sub-category object with the incremented version.

Error codes

Code	Reason
`400`	Validation error or missing `id`.
`401`	Missing or invalid API key / session.
`403`	Insufficient role.
`409`	A sub-category with that name already exists.

Delete a sub-category (soft-delete)

DELETE /api/v1/sub-categories?id={subCategoryId}

Soft-deletes a sub-category by setting its deletedAt timestamp. The version is incremented.

Query parameters

Parameter	Required	Type	Description
`id`	Yes	string	Sub-category ID to delete.

Response `200`

{
  "success": true
}

Error codes

Code	Reason
`400`	Missing `id`, entity not found, or entity already deleted.
`401`	Missing or invalid API key / session.
`403`	Insufficient role.

Role requirements

Method	Minimum role
GET	`viewer`
POST	`editor`
PUT	`editor`
DELETE	`editor`

Business Hierarchy

Learn more about organising categories and sub-categories in the platform UI.

Overview

Core APIs

Studio

Data

Algorithms

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Documentation Index

​Base path

​Categories

​List categories

​Query parameters

​Response 200

​Error codes

​Create a category

​Request body

​Custom field object

​Example request

​Response 201

​Error codes

​Update a category

​Request body

​Response 200

​Error codes

​Delete a category (soft-delete)

​Query parameters

​Response 200

​Error codes

​Sub-categories

​List sub-categories

​Query parameters

​Response 200

​Create a sub-category

​Request body

​Response 201

​Error codes

​Update a sub-category

​Request body

​Response 200

​Error codes

​Delete a sub-category (soft-delete)

​Query parameters

​Response 200

​Error codes

​Role requirements

Business Hierarchy

Base path

Categories

List categories

Query parameters

Response `200`

Error codes

Create a category

Request body

Custom field object

Example request

Response `201`

Error codes

Update a category

Request body

Response `200`

Error codes

Delete a category (soft-delete)

Query parameters

Response `200`

Error codes

Sub-categories

List sub-categories

Query parameters

Response `200`

Create a sub-category

Request body

Response `201`

Error codes

Update a sub-category

Request body

Response `200`

Error codes

Delete a sub-category (soft-delete)

Query parameters

Response `200`

Error codes

Role requirements