💵 Cash Transaction API

Admin/Employee: view transactions; Admin: update status

Cash Transactions

GET /transactions Admin / Employee

List all cash transactions with filters and pagination.

Query Parameters

  • status (optional: pending, completed, cancelled)
  • invoice_id (optional, filter by invoice ID)
  • processed_by (optional, filter by user ID who processed the transaction)
  • date_from (optional, filter from date)
  • date_to (optional, filter until date)
  • page, per_page (optional; default 1 / 20)

Example:

GET /transactions?status=completed&invoice_id=1&page=1&per_page=20

200 OK

{
  "transactions": [
    {
      "id": 1,
      "invoice_id": 1,
      "amount_due": "116.00",
      "amount_given": "120.00",
      "change_amount": "4.00",
      "status": "completed",
      "processed_by": 1,
      "processed_by_name": "John Doe",
      "completed_at": "2025-12-13T14:30:25",
      "created_at": "2025-12-13T14:30:22",
      "updated_at": "2025-12-13T14:30:25"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
GET /transactions/<transaction_id> Admin / Employee

Get transaction detail including associated invoice information.

200 OK

{
  "transaction": {
    "id": 1,
    "invoice_id": 1,
    "amount_due": "116.00",
    "amount_given": "120.00",
    "change_amount": "4.00",
    "status": "completed",
    "processed_by": 1,
    "processed_by_name": "John Doe",
    "completed_at": "2025-12-13T14:30:25",
    "created_at": "2025-12-13T14:30:22",
    "updated_at": "2025-12-13T14:30:25",
    "invoice": {
      "id": 1,
      "invoice_number": "INV-2025-DEC-13A",
      "total_amount": "116.00",
      "status": "paid",
      "payment_status": "paid",
      "payment_method": "cash"
    }
  }
}

404 Not Found

PATCH /transactions/<transaction_id>/status Admin Only

Update transaction status. Only admin can update transaction status.

Request Body (JSON)

  • status (optional: pending, completed, cancelled)

Example Request:

PATCH /transactions/1/status
Content-Type: application/json

{
  "status": "cancelled"
}

200 OK

{
  "transaction": {
    "id": 1,
    "invoice_id": 1,
    "amount_due": "116.00",
    "amount_given": "120.00",
    "change_amount": "4.00",
    "status": "cancelled",
    "processed_by": 1,
    "processed_by_name": "John Doe",
    "completed_at": "2025-12-13T14:30:25",
    "created_at": "2025-12-13T14:30:22",
    "updated_at": "2025-12-13T14:30:30"
  }
}

400 Invalid status value

404 Transaction not found

Error Example:

{
  "message": "Invalid status. Must be one of: pending, completed, cancelled"
}

Notes

  • Cash transactions are created when an invoice is paid using the cash payment method via the invoice payment endpoint.
  • Transactions track the amount due, amount given by the customer, and calculated change amount.
  • Transaction status can be: pending, completed, or cancelled.
  • When a transaction is completed, it automatically updates the associated invoice to paid status.
  • The processed_by field tracks which user (admin/employee) processed the transaction.
  • All date fields are in ISO 8601 format (UTC).
  • Only admin users can update transaction status.