Skip to main content

🏷️ Categories API

The Categories API allows you to manage transaction categories for organizing and classifying financial transactions. Categories can be hierarchical (parent-child relationships) and support custom icons, colors, and descriptions.

📡 Base URL​

All categories endpoints are prefixed with:

/wp-json/pika/v1/categories

🚀 Endpoints​

Get All Categories​

Retrieve all categories for the authenticated user.

Endpoint: GET /wp-json/pika/v1/categories

Headers:

  • Cookie: Authentication cookie

Query Parameters:

  • type (optional): Filter by category type (income, expense, transfer)
  • parent_id (optional): Filter by parent category ID
  • include_system (optional): Include system categories (default: true)

Response:

[
    {
        "id": "33",
        "name": "Personal Care",
        "icon": "smile",
        "color": "#FFFFFF",
        "bgColor": "#48BB78",
        "description": "Personal care expenses",
        "isSystem": true,
        "isParent": true,
        "type": "expense",
        "parentId": null,
        "children": [
            {
                "id": "36",
                "name": "Fitness",
                "icon": "dumbbell",
                "color": "#FFFFFF",
                "bgColor": "#2F855A",
                "description": "Fitness and gym expenses",
                "isSystem": true,
                "isParent": false,
                "type": "expense",
                "parentId": "33",
                "children": []
            },
            ...
        ]
    },
    ...
]

Example Request:

curl -X GET "http://localhost:8000/wp-json/pika/v1/categories?type=expense" \
  -H "Cookie: pika_token=token"

Get Category by ID​

Retrieve a specific category by its ID.

Endpoint: GET /wp-json/pika/v1/categories/{id}

Headers:

  • Cookie: Authentication cookie

Response:

{
    "id": "68",
    "name": "Home WiFi",
    "icon": "house-wifi",
    "color": "#ffffff",
    "bgColor": "#EAB308",
    "description": "",
    "isSystem": false,
    "isParent": false,
    "type": "expense",
    "parentId": "17",
    "children": []
}

Example Request:

curl -X GET http://localhost:8000/wp-json/pika/v1/categories/68 \
  -H "Cookie: pika_token=token"

Create Category​

Create a new category.

Endpoint: POST /wp-json/pika/v1/categories

Headers:

  • Cookie: Authentication cookie
  • Content-Type: application/json

Request Body:

{
    "name":"Test Category",
    "description":"Description content",
    "icon":"wallet",
    "bgColor":"#3B82F6",
    "color":"#ffffff",
    "type":"expense",
    "parentId":"29"
}

Required Fields:

  • name (string): Category name
  • type (string): Category type (income, expense, transfer)

Optional Fields:

  • icon (string): Icon identifier
  • color (string): Text color (hex format)
  • bgColor (string): Background color (hex format)
  • description (string): Category description
  • parentId (integer): Parent category ID for subcategories

Response:

{
    "id": "69",
    "name": "Test Category",
    "icon": "wallet",
    "color": "#ffffff",
    "bgColor": "#3B82F6",
    "description": "Description content",
    "isSystem": false,
    "isParent": false,
    "type": "expense",
    "parentId": "29",
    "children": []
}

Example Request:

curl -X POST http://localhost:8000/wp-json/pika/v1/categories \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Test Category",
    "description":"Description content",
    "icon":"wallet",
    "bgColor":"#3B82F6",
    "color":"#ffffff",
    "type":"expense",
    "parentId":"29"
  }'

Update Category​

Update an existing category.

Endpoint: PUT /wp-json/pika/v1/categories/{id}

Headers:

  • Cookie: Authentication cookie
  • Content-Type: application/json

Request Body:

{
    "name":"Test Category Updated",
    "icon":"eye",
    "bgColor":"#F97316",
}

Response:

{
    "id": "69",
    "name": "Test Category Updated",
    "icon": "eye",
    "color": "#ffffff",
    "bgColor": "#F97316",
    "description": "Description content",
    "isSystem": false,
    "isParent": false,
    "type": "expense",
    "parentId": "29",
    "children": []
}

Example Request:

curl -X PUT http://localhost:8000/wp-json/pika/v1/categories/29 \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Test Category Updated",
    "icon":"eye",
    "bgColor":"#F97316",
  }'

Delete Category​

Delete a category. System categories cannot be deleted.

Endpoint: DELETE /wp-json/pika/v1/categories/{id}

Headers:

  • Cookie: Authentication cookie

Response:

{"message":"Category deleted successfully"}

Example Request:

curl -X DELETE http://localhost:8000/wp-json/pika/v1/categories/29 \
  -H "Cookie: pika_token=token"

🎨 Category Properties​

Icon Options​

Available Icons:

  • All Lucide icons

Color Format​

  • Text Color: Hex color code (e.g., #ff6b6b)
  • Background Color: Hex color code (e.g., #fff5f5)
  • Recommended: Use contrasting colors for readability

Category Types​

  • income: Money coming in (salary, investments, gifts)
  • expense: Money going out (food, transportation, bills)
  • transfer: Moving money between accounts

🔄 Hierarchical Categories​

Parent-Child Relationships​

{
    "id": "29",
    "name": "Education",
    "icon": "graduation-cap",
    "color": "#FFFFFF",
    "bgColor": "#4299E1",
    "description": "Education expenses",
    "isSystem": true,
    "isParent": true,
    "type": "expense",
    "parentId": null,
    "children": [
        {
            "id": "31",
            "name": "Books",
            "icon": "book",
            "color": "#FFFFFF",
            "bgColor": "#2C5282",
            "description": "Books and supplies",
            "isSystem": true,
            "isParent": false,
            "type": "expense",
            "parentId": "29",
            "children": []
        },
        {
            "id": "32",
            "name": "Courses",
            "icon": "notebook-pen",
            "color": "#FFFFFF",
            "bgColor": "#2A4365",
            "description": "Online courses and training",
            "isSystem": true,
            "isParent": false,
            "type": "expense",
            "parentId": "29",
            "children": []
        },
        ...
    ]
}

🚨 Error Responses​

Category Name Not Unique​

This error occurs when attempting to create or update a category with a name that is already in use by another category at the same level.

{
  "code": "category_name_not_unique",
  "message": "Category name is not unique.",
  "data": {
    "status": 400
  }
}

Category Not Found​

This error is returned when an operation is requested on a category that does not exist in the database.

{
  "code": "category_not_found",
  "message": "Category not found.",
  "data": {
    "status": 404
  }
}

Invalid Parent Category​

This error indicates that the specified parent category ID is either non-existent or invalid, preventing the creation of a sub-category relationship.

{
  "code": "invalid_parent_category",
  "message": "Invalid parent category.",
  "data": {
    "status": 400
  }
}

Invalid Category Type​

This error is triggered when the type field for a category is not one of the allowed values.

{
  "code": "invalid_type",
  "message": "Invalid category type. Type must be one of the following: income, expense, transfer.",
  "data": {
    "status": 400
  }
}

Invalid Category Name​

This response is used when the provided category name does not meet validation criteria (e.g., it is empty, too long, or contains invalid characters).

{
  "code": "invalid_name",
  "message": "Invalid category name.",
  "data": {
    "status": 400
  }
}

Parent Cannot Be Child​

This error prevents creating a circular dependency where a parent category is assigned as a child of one of its own descendants.

{
  "code": "parent_cannot_be_child",
  "message": "Parent category can not be a child category.",
  "data": {
    "status": 400
  }
}

Category Has Children​

This error occurs when attempting to delete a category that still has sub-categories (children) linked to it. The child categories must be deleted or reassigned first.

{
  "code": "category_has_children",
  "message": "Category has children. Please delete the children first.",
  "data": {
    "status": 400
  }
}

📚 Related Documentation​