Add user-facing income/revenue submission endpoint #9

New issue

Closed

opened 2026-04-25 13:45:54 +00:00 by padreug · 1 comment

padreug commented

2026-04-25 13:45:54 +00:00

Owner

Summary

Currently, revenue entries can only be created via POST /castle/api/v1/entries/revenue which requires admin_key (from the require_admin_key decorator). Regular users cannot submit income/revenue entries.

We need a user-facing income submission endpoint that mirrors the existing expense submission flow — users submit with invoice_key, the entry gets a ! (pending) flag, and an admin approves or rejects it.

Proposed Endpoint

POST /castle/api/v1/entries/income

Auth: require_invoice_key (same as expense submission)

Request model (similar to ExpenseEntry):

class IncomeEntry(BaseModel):
    description: str
    amount: Decimal           # satoshis or fiat amount
    revenue_account: str      # account name or ID (must be a Revenue/Income account)
    reference: Optional[str] = None
    currency: Optional[str] = None  # EUR, USD, etc.
    entry_date: Optional[datetime] = None

Behavior:

Validate user has permission on the revenue account (new SUBMIT_INCOME permission type, or reuse SUBMIT_EXPENSE)
Create journal entry with ! (pending) flag
Entry follows same approval/rejection flow as expenses
Accounting postings: Debit Assets:* (e.g., Assets:Cash, Assets:Bank), Credit Income:*

Context

The standalone Castle accounting app (frontend) is being built to allow team members to record both expenses AND income. The expense flow works today, but income submission is blocked because the endpoint requires admin privileges.

The goal is for organizations where multiple people receive income on behalf of the entity — they should be able to log it for approval, just like expenses.

Permission Considerations

Consider adding a SUBMIT_INCOME permission type alongside SUBMIT_EXPENSE
Or reuse SUBMIT_EXPENSE for both (rename to SUBMIT_ENTRY?)
Permission should be grantable on specific Revenue/Income accounts

## Summary Currently, revenue entries can only be created via `POST /castle/api/v1/entries/revenue` which requires `admin_key` (from the `require_admin_key` decorator). Regular users cannot submit income/revenue entries. We need a user-facing income submission endpoint that mirrors the existing expense submission flow — users submit with `invoice_key`, the entry gets a `!` (pending) flag, and an admin approves or rejects it. ## Proposed Endpoint ``` POST /castle/api/v1/entries/income ``` **Auth**: `require_invoice_key` (same as expense submission) **Request model** (similar to `ExpenseEntry`): ```python class IncomeEntry(BaseModel): description: str amount: Decimal # satoshis or fiat amount revenue_account: str # account name or ID (must be a Revenue/Income account) reference: Optional[str] = None currency: Optional[str] = None # EUR, USD, etc. entry_date: Optional[datetime] = None ``` **Behavior**: 1. Validate user has permission on the revenue account (new `SUBMIT_INCOME` permission type, or reuse `SUBMIT_EXPENSE`) 2. Create journal entry with `!` (pending) flag 3. Entry follows same approval/rejection flow as expenses 4. Accounting postings: Debit `Assets:*` (e.g., `Assets:Cash`, `Assets:Bank`), Credit `Income:*` ## Context The standalone Castle accounting app (frontend) is being built to allow team members to record both expenses AND income. The expense flow works today, but income submission is blocked because the endpoint requires admin privileges. The goal is for organizations where multiple people receive income on behalf of the entity — they should be able to log it for approval, just like expenses. ## Permission Considerations - Consider adding a `SUBMIT_INCOME` permission type alongside `SUBMIT_EXPENSE` - Or reuse `SUBMIT_EXPENSE` for both (rename to `SUBMIT_ENTRY`?) - Permission should be grantable on specific Revenue/Income accounts