Skip to main content

​
Overview

The business hierarchy is a two-level organizational structure for your offers. Categories are top-level groupings and sub-categories are nested beneath them. This hierarchy provides logical organization, drives custom field schemas, and enables category-level rules and reporting.

​
Categories

A category represents a top-level business domain or product line (e.g., “Credit Cards”, “Personal Loans”, “Insurance Products”).

​
Category Fields

FieldTypeDescription
namestringDisplay name of the category
descriptionstringOptional description
iconstringIcon identifier for the UI
colorstringHex color code for visual distinction
statusenumactive or archived
ordinalnumberDisplay order position
customFieldsarraySchema definition for fields on offers in this category

​
Custom Fields

Categories define a custom field schema that applies to all offers within the category. Each custom field has:
PropertyTypeDescription
namestringField identifier (used as key in offer data)
labelstringDisplay label in the UI
typeenumField type
requiredbooleanWhether the field must be filled
optionsstring[]Choices for select type fields
formulastringFormula expression for computed type fields
outputTypeenumOutput data type for computed fields: text, number, decimal, boolean

​
Custom Field Types

TypeDescriptionExample
textFree-text stringProduct description, internal notes
numberInteger valuePoints multiplier, term length
selectSingle choice from optionsRisk tier, product variant
booleanTrue/false togglePre-approved flag, promotional
dateDate valueEffective date, review date
computedFormula-evaluated at decision timePersonalized rate, dynamic discount
Computed fields are the foundation of dynamic computed values. They let you define formulas like base_rate * (1 - customer.loyalty_score * 0.01) that are evaluated per customer at decision time.

​
Computed Field Formulas

Computed fields use the formula engine with three variable namespaces:
NamespaceSourceExample
(bare name)Other custom field values on the offerbase_rate, annual_fee
customer.*Enriched data from schema tablescustomer.loan_amount, customer.credit_score
attributes.*Request-time attributes from the Recommend APIattributes.tier, attributes.channel
Example computed field: 
Name: personalized_rate
Formula: base_rate * (1 - customer.loyalty_score * 0.01)
Output Type: decimal
See Computed Values for the full formula syntax reference.

​
Sub-Categories

Sub-categories provide a second level of grouping beneath a category (e.g., “Premium Cards” and “Travel Cards” under “Credit Cards”).

​
Sub-Category Fields

FieldTypeDescription
namestringDisplay name
descriptionstringOptional description
categoryIdstringParent category ID
ordinalnumberDisplay order within the parent category

​
Cascade Behavior

Deleting a category will cascade-delete all its sub-categories. However, offers are unlinked (their categoryId and subCategoryId are set to null) rather than deleted, preserving historical data and interaction history.
Deleting a sub-category unlinks its offers in the same way — offers are preserved but lose their sub-category association.

​
Creating a Category

1

Navigate to Business Hierarchy

Go to Studio > Business Hierarchy in the sidebar.
2

Click Create Category

Click the + New Category button.
3

Fill in category details

Enter the name, description, icon, and color.
4

Define custom fields

Add custom fields that will apply to all offers in this category. For each field, specify the name, label, type, and whether it is required.
5

Add computed fields (optional)

For computed fields, enter the formula expression and select the output type. Click Validate to check the formula syntax before saving.
6

Save

Save the category. It is immediately available for creating offers and sub-categories.

​
Creating a Sub-Category

1

Select parent category

In the Business Hierarchy view, click on the category you want to add a sub-category to.
2

Click Add Sub-Category

Click the + Sub-Category button within the category detail panel.
3

Fill in details

Enter the sub-category name and optional description.
4

Save

Save the sub-category. It appears nested under its parent category.

​
API Reference

​
Create a Category

POST /api/v1/categories
Content-Type: application/json
Request body: 
{
  "name": "Personal Loans",
  "description": "Personal lending products",
  "icon": "banknotes",
  "color": "#6366f1",
  "status": "active",
  "ordinal": 2,
  "customFields": [
    { "name": "base_rate", "label": "Base APR", "type": "number", "required": true },
    { "name": "term_months", "label": "Term (Months)", "type": "number", "required": true },
    { "name": "min_credit_score", "label": "Min Credit Score", "type": "number", "required": false },
    {
      "name": "personalized_rate",
      "label": "Personalized Rate",
      "type": "computed",
      "formula": "base_rate * (1 - customer.loyalty_score * 0.01)",
      "outputType": "decimal"
    }
  ]
}
Response (201 Created): 
{
  "id": "cat_personal_loans",
  "name": "Personal Loans",
  "description": "Personal lending products",
  "icon": "banknotes",
  "color": "#6366f1",
  "status": "active",
  "ordinal": 2,
  "customFields": [ ... ],
  "createdAt": "2026-03-10T14:30:00Z",
  "updatedAt": "2026-03-10T14:30:00Z"
}

​
Create a Sub-Category

POST /api/v1/categories/:categoryId/sub-categories
Content-Type: application/json

{
  "name": "Debt Consolidation",
  "description": "Loans for consolidating existing debt",
  "ordinal": 1
}

​
List Categories

GET /api/v1/categories
Returns all categories with their sub-categories and custom field schemas.

​
Delete a Category

DELETE /api/v1/categories/:id
This cascade-deletes all sub-categories and unlinks all offers. This action cannot be undone.