Categories

Categories provide a way to classify and organize transactions, invoices, and bills in Crane Ledger. They help with reporting, budgeting, and financial analysis by grouping similar transactions together.

The Category Object

{
  "id": "cat_xxxxxxxxxxxxxxxx",
  "object": "category",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Office Supplies",
  "description": "Expenses for office supplies and stationery",
  "category_type": "expense",
  "color": "#3B82F6",
  "is_active": true,
  "parent_id": null,
  "subcategories": [],
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T10:00:00Z"
}

Attributes

List Categories

Returns a list of categories for the organization with optional filtering.

Path Parameters

Query Parameters

Response

{
  "object": "list",
  "data": [
    {
      "id": "cat_xxxxxxxxxxxxxxxx",
      "name": "Office Supplies",
      "category_type": "expense",
      "color": "#3B82F6",
      "is_active": true,
      "parent_id": null
    },
    {
      "id": "cat_yyyyyyyyyyyyyyyy",
      "name": "Consulting Revenue",
      "category_type": "income",
      "color": "#10B981",
      "is_active": true,
      "parent_id": null
    }
  ],
  "has_more": false,
  "total_count": 2
}

Create Category

Creates a new transaction category for organizing financial data.

Path Parameters

Request Body

Response

{
  "id": "cat_xxxxxxxxxxxxxxxx",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Travel Expenses",
  "description": "Business travel and transportation costs",
  "category_type": "expense",
  "color": "#F59E0B",
  "is_active": true,
  "parent_id": null,
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:30:00Z"
}

Get Category

Retrieves the details of a specific category.

Path Parameters

Response

Returns the complete category object.

Update Category

Updates an existing category.

Path Parameters

Request Body

Delete Category

Deletes a category. Categories with associated transactions cannot be deleted.

Path Parameters

Category Types

Income Categories

• Sales Revenue: Product and service sales
• Service Income: Consulting and professional services
• Interest Income: Bank interest and investment returns
• Other Income: Miscellaneous revenue sources

Expense Categories

• Cost of Goods Sold: Direct product costs
• Operating Expenses: Day-to-day business costs
• Administrative: Management and administrative costs
• Marketing: Advertising and promotional expenses
• Professional Services: Legal, accounting, consulting fees

Category Hierarchy

Categories support hierarchical organization:

{
  "name": "Operating Expenses",
  "subcategories": [
    {
      "name": "Office Supplies",
      "parent_id": "cat_operating_expenses"
    },
    {
      "name": "Utilities",
      "parent_id": "cat_operating_expenses"
    }
  ]
}

Best Practices

Naming Conventions

• Use clear, descriptive names
• Be consistent with terminology
• Avoid abbreviations that may not be clear

Organization

• Group similar expenses together
• Create subcategories for detailed tracking
• Use consistent color coding for visual organization

Maintenance

• Regularly review and update categories
• Deactivate unused categories rather than deleting
• Archive historical categories when restructuring

• ✨ For LLMs/AI assistants: Read our structured API reference