Skip to main content

💰 Transactions API

The Transactions API is the core of Pika's financial management system. It allows you to create, read, update, and delete financial transactions including income, expenses, and transfers between accounts.

📡 Base URL​

All transactions endpoints are prefixed with:

/wp-json/pika/v1/transactions

🚀 Endpoints​

Get All Transactions​

Retrieve all transactions for the authenticated user with optional filtering and pagination.

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

Headers:

  • Cookie: Authentication cookie

Query Parameters:

  • type (optional): Filter by transaction type (income, expense, transfer)
  • category_id (optional): Filter by category ID
  • account_id (optional): Filter by account ID
  • person_id (optional): Filter by person ID
  • date_from (optional): Filter transactions from date (YYYY-MM-DD)
  • date_to (optional): Filter transactions to date (YYYY-MM-DD)
  • amount_min (optional): Minimum amount filter
  • amount_max (optional): Maximum amount filter
  • tags (optional): Comma-separated tag IDs
  • page (optional): Page number for pagination (default: 1)
  • per_page (optional): Items per page (default: 20, max: 100)

Response:

[
    {
        "id": "81",
        "title": "hello",
        "amount": "90.0000",
        "date": "2025-08-23T05:19:18+00:00",
        "type": "expense",
        "category": {
            "id": "31",
            "name": "Books",
            "icon": "book",
            "color": "#FFFFFF",
            "bgColor": "#2C5282",
            "description": "Books and supplies",
            "isSystem": true,
            "isParent": false,
            "type": "expense",
            "parentId": "29",
            "children": []
        },
        "account": {
            "id": "1",
            "name": "Federal",
            "description": "Main Account",
            "avatar": {
                "id": "1",
                "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/account-6889ac3ac6f73-1753852986.jpg",
                "type": "image",
                "name": "1000118509.jpg",
                "size": "9444"
            },
            "lastTransactionAt": null,
            "totalTransactions": 0,
            "balance": "-50921.7500",
            "icon": "wallet",
            "bgColor": "#3B82F6",
            "color": "#ffffff"
        },
        "person": null,
        "toAccount": {
            "id": "2",
            "name": "Wallet",
            "description": "",
            "avatar": null,
            "lastTransactionAt": null,
            "totalTransactions": 0,
            "balance": "400.0000",
            "icon": "wallet",
            "bgColor": "#3B82F6",
            "color": "#ffffff"
        },
        "note": "",
        "attachments": [],
        "tags": []
    },
    {
        "id": "80",
        "title": "test",
        "amount": "89.0000",
        "date": "2025-08-06T23:34:18+00:00",
        "type": "expense",
        "category": {
            "id": "60",
            "name": "Food Order",
            "icon": "hamburger",
            "color": "#ffffff",
            "bgColor": "#0891B2",
            "description": "Food order from online",
            "isSystem": false,
            "isParent": false,
            "type": "expense",
            "parentId": "1",
            "children": []
        },
        "account": {
            "id": "1",
            "name": "Federal",
            "description": "Main Account",
            "avatar": {
                "id": "1",
                "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/account-6889ac3ac6f73-1753852986.jpg",
                "type": "image",
                "name": "1000118509.jpg",
                "size": "9444"
            },
            "lastTransactionAt": null,
            "totalTransactions": 0,
            "balance": "-50921.7500",
            "icon": "wallet",
            "bgColor": "#3B82F6",
            "color": "#ffffff"
        },
        "person": null,
        "toAccount": null,
        "note": "",
        "attachments": [],
        "tags": []
    },
    {
        "id": "79",
        "title": "ash",
        "amount": "89.0000",
        "date": "2025-08-06T23:30:35+00:00",
        "type": "expense",
        "category": {
            "id": "2",
            "name": "Dining Out",
            "icon": "utensils",
            "color": "#FFFFFF",
            "bgColor": "#DD6B20",
            "description": "Restaurant and dining out expenses",
            "isSystem": true,
            "isParent": false,
            "type": "expense",
            "parentId": "1",
            "children": []
        },
        "account": {
            "id": "1",
            "name": "Federal",
            "description": "Main Account",
            "avatar": {
                "id": "1",
                "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/account-6889ac3ac6f73-1753852986.jpg",
                "type": "image",
                "name": "1000118509.jpg",
                "size": "9444"
            },
            "lastTransactionAt": null,
            "totalTransactions": 0,
            "balance": "-50921.7500",
            "icon": "wallet",
            "bgColor": "#3B82F6",
            "color": "#ffffff"
        },
        "person": null,
        "toAccount": null,
        "note": "",
        "attachments": [],
        "tags": []
    }
]

Example Request:

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

Get Transaction by ID​

Retrieve a specific transaction by its ID.

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

Headers:

  • Cookie: Authentication cookie

Response:

{
    "id": "81",
    "title": "hello",
    "amount": "90.0000",
    "date": "2025-08-23T05:19:18+00:00",
    "type": "expense",
    "category": {
        "id": "31",
        "name": "Books",
        "icon": "book",
        "color": "#FFFFFF",
        "bgColor": "#2C5282",
        "description": "Books and supplies",
        "isSystem": true,
        "isParent": false,
        "type": "expense",
        "parentId": "29",
        "children": []
    },
    "account": {
        "id": "1",
        "name": "Federal",
        "description": "Main Account",
        "avatar": {
            "id": "1",
            "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/account-6889ac3ac6f73-1753852986.jpg",
            "type": "image",
            "name": "1000118509.jpg",
            "size": "9444"
        },
        "lastTransactionAt": null,
        "totalTransactions": 0,
        "balance": "-50921.7500",
        "icon": "wallet",
        "bgColor": "#3B82F6",
        "color": "#ffffff"
    },
    "person": null,
    "toAccount": {
        "id": "2",
        "name": "Wallet",
        "description": "",
        "avatar": null,
        "lastTransactionAt": null,
        "totalTransactions": 0,
        "balance": "400.0000",
        "icon": "wallet",
        "bgColor": "#3B82F6",
        "color": "#ffffff"
    },
    "note": "",
    "attachments": [],
    "tags": []
}

Example Request:

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

Create Transaction​

Create a new transaction.

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

Headers:

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

Request Body:

{
  "title":"Test tnx",
  "amount":190,
  "date":"2025-09-02T04:17:48.301Z",
  "type":"expense",
  "categoryId":"31",
  "accountId":"1",
  "personId":null,
  "toAccountId":null,
  "note":"",
  "tags":["5"],
  "attachments":[]
}

Required Fields:

  • title (string): Transaction title/description
  • amount (number): Transaction amount (positive number)
  • date (string): Transaction date (YYYY-MM-DD format)
  • type (string): Transaction type (income, expense, transfer)
  • categoryId (integer): Category ID
  • accountId (integer): Account ID

Optional Fields:

  • personId (integer): Associated person ID
  • tags (array): Array of tag IDs
  • attachments (array): Array of attachment IDs
  • note (string): Additional notes
  • `toAccount (string|integer): Account ID

Response:

{
    "id": "82",
    "title": "Test tnx",
    "amount": "190.0000",
    "date": "2025-09-02T04:17:48+00:00",
    "type": "expense",
    "category": {
        "id": "31",
        "name": "Books",
        "icon": "book",
        "color": "#FFFFFF",
        "bgColor": "#2C5282",
        "description": "Books and supplies",
        "isSystem": true,
        "isParent": false,
        "type": "expense",
        "parentId": "29",
        "children": []
    },
    "account": {
        "id": "1",
        "name": "Federal",
        "description": "Main Account",
        "avatar": {
            "id": "1",
            "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/account-6889ac3ac6f73-1753852986.jpg",
            "type": "image",
            "name": "1000118509.jpg",
            "size": "9444"
        },
        "lastTransactionAt": null,
        "totalTransactions": 0,
        "balance": "-51111.7500",
        "icon": "wallet",
        "bgColor": "#3B82F6",
        "color": "#ffffff"
    },
    "person": null,
    "toAccount": null,
    "note": "",
    "attachments": [],
    "tags": [
        {
            "id": "5",
            "name": "Personal",
            "color": "#FFFFFF",
            "bgColor": "#DD6B20",
            "icon": "user",
            "description": "Personal transactions",
            "isSystem": true
        }
    ]
}

Example Request:

curl -X POST http://localhost:8000/wp-json/pika/v1/transactions \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "title":"Test tnx",
    "amount":190,
    "date":"2025-09-02T04:17:48.301Z",
    "type":"expense",
    "categoryId":"31",
    "accountId":"1",
    "personId":null,
    "toAccountId":null,
    "note":"",
    "tags":["5"],
    "attachments":[]
  }'

Update Transaction​

Update an existing transaction.

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

Headers:

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

Request Body:

{
  "title":"Test tnx - updated",
  "amount":190,
  "date":"2025-09-02T04:17:48+00:00",
  "type":"expense",
  "categoryId":"31",
  "accountId":"1",
  "personId":null,
  "toAccountId":null,
  "note":"",
  "tags":["5"],
  "attachments":[]
}

Response:

{
    "id": "82",
    "title": "Test tnx - updated",
    "amount": "190.0000",
    "date": "2025-09-02T04:17:48+00:00",
    "type": "expense",
    "category": {
        "id": "31",
        "name": "Books",
        "icon": "book",
        "color": "#FFFFFF",
        "bgColor": "#2C5282",
        "description": "Books and supplies",
        "isSystem": true,
        "isParent": false,
        "type": "expense",
        "parentId": "29",
        "children": []
    },
    "account": {
        "id": "1",
        "name": "Federal",
        "description": "Main Account",
        "avatar": {
            "id": "1",
            "url": "http:\/\/localhost:8000\/wp-content\/uploads\/pika\/avatars\/account-6889ac3ac6f73-1753852986.jpg",
            "type": "image",
            "name": "1000118509.jpg",
            "size": "9444"
        },
        "lastTransactionAt": null,
        "totalTransactions": 0,
        "balance": "-51111.7500",
        "icon": "wallet",
        "bgColor": "#3B82F6",
        "color": "#ffffff"
    },
    "person": null,
    "toAccount": null,
    "note": "",
    "attachments": [],
    "tags": [
        {
            "id": "5",
            "name": "Personal",
            "color": "#FFFFFF",
            "bgColor": "#DD6B20",
            "icon": "user",
            "description": "Personal transactions",
            "isSystem": true
        }
    ]
}

Example Request:

curl -X PUT http://localhost:8000/wp-json/pika/v1/transactions/82 \
  -H "Cookie: pika_token=token" \
  -H "Content-Type: application/json" \
  -d '{
    "title":"Test tnx - updated",
    "amount":190,
    "date":"2025-09-02T04:17:48+00:00",
    "type":"expense",
    "categoryId":"31",
    "accountId":"1",
    "personId":null,
    "toAccountId":null,
    "note":"",
    "tags":["5"],
    "attachments":[]
  }'

Delete Transaction​

Delete a transaction.

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

Headers:

  • Cookie: Authentication cookie

Response:

{"message":"Transaction deleted successfully"}

Example Request:

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

💳 Transaction Types​

Income Transactions​

  • Purpose: Money coming into accounts
  • Examples: Salary, investments, gifts, refunds
  • Amount: Always positive
  • Effect: Increases account balance

Expense Transactions​

  • Purpose: Money going out from accounts
  • Examples: Food, transportation, bills, shopping
  • Amount: Always positive (system handles negative internally)
  • Effect: Decreases account balance

Transfer Transactions​

  • Purpose: Moving money between accounts
  • Examples: Savings transfers, account rebalancing
  • Amount: Always positive
  • Effect: Decreases source account, increases destination account

🔗 Related Data​

Categories​

  • Each transaction must have a category
  • Categories determine transaction classification
  • Support for hierarchical organization

Accounts​

  • Transactions are linked to accounts
  • Affects account balance calculations
  • Support for multiple account types

People​

  • Optional association with people
  • Useful for shared expenses or tracking
  • Supports avatars and contact information

Tags​

  • Flexible labeling system
  • Multiple tags per transaction
  • Color-coded for visual organization

Attachments​

  • File attachments (receipts, invoices)
  • Support for images and documents
  • Automatic file type detection

🚨 Error Responses​

Invalid Title​

This error is returned when a transaction's title is missing, empty, or doesn't meet validation requirements.

{
  "code": "invalid_title",
  "message": "Invalid title",
  "data": {
    "status": 400
  }
}

Invalid Amount​

This error occurs when the amount provided for a transaction is not a number greater than 0. 💰

{
  "code": "invalid_amount",
  "message": "Invalid amount, must be greater than 0",
  "data": {
    "status": 400
  }
}

Invalid Date​

This response is used when the transaction date is not a valid date string or is in an unrecognized format. 🗓️

{
  "code": "invalid_date",
  "message": "Invalid date",
  "data": {
    "status": 400
  }
}

Invalid Type​

This error is triggered if the transaction type is not one of the three accepted values: "income", "expense", or "transfer".

{
  "code": "invalid_type",
  "message": "Invalid type, must be \"income\", \"expense\" or \"transfer\"",
  "data": {
    "status": 400
  }
}

Invalid Category ID​

This error indicates that the category ID associated with the transaction is either malformed or doesn't exist.

{
  "code": "invalid_category_id",
  "message": "Invalid category id",
  "data": {
    "status": 400
  }
}

Invalid Account ID​

This response is used when the transaction's source account ID is invalid or doesn't correspond to an existing account.

{
  "code": "invalid_account_id",
  "message": "Invalid account id",
  "data": {
    "status": 400
  }
}

Invalid Person ID​

This error occurs when the person ID linked to the transaction is invalid or not found.

{
  "code": "invalid_person_id",
  "message": "Invalid person id",
  "data": {
    "status": 400
  }
}

Invalid To Account ID​

Specifically for transfers, this error is returned when the destination account ID (to_account_id) is invalid.

{
  "code": "invalid_to_account_id",
  "message": "Invalid to account id",
  "data": {
    "status": 400
  }
}

Invalid Tags​

This error indicates that the data provided for tags is not in the correct format (e.g., not an array of valid tag IDs).

{
  "code": "invalid_tags",
  "message": "Invalid tags",
  "data": {
    "status": 400
  }
}

Invalid Attachments​

This response is used when the data for attachments is malformed, such as not being an array of valid attachment objects. 📎

{
  "code": "invalid_attachments",
  "message": "Invalid attachments",
  "data": {
    "status": 400
  }
}

Transaction Not Found​

This error is returned when an attempt is made to access or modify a transaction that does not exist.

{
  "code": "not_found",
  "message": "Transaction not found",
  "data": {
    "status": 404
  }
}

📚 Related Documentation​