Add Refund entry type to accounting spec #2

New issue

Open

opened 2026-01-02 18:55:49 +00:00 by padreug · 0 comments

padreug commented

2026-01-02 18:55:49 +00:00

Owner

Summary

We need to formally add a Refund entry type to our accounting specification. Refunds occur when a vendor/service provider credits back an overcharge.

Proposed Entry Type

Entry Type	Links	Tags	Key Metadata
Refund	`^exp-{original-entry-id}`, `^castle-{entry-id}`	`#expense-entry`	user-id, entry-id, source

Transaction Format

2025-10-31 * "Vendor Refund" #expense-entry ^castle-{entry-id} ^exp-{entry-id}
  source: "castle-api"
  entry-id: "{entry-id}"
  Liabilities:Payable:User-xxxxx                   +XX.XX EUR @@ XXXXX SATS
  Expenses:Category                                -XX.XX EUR @@ XXXXX SATS

Accounting Logic

Credit to Expenses (negative amount): Reduces the original expense since the amount was overcharged
Debit to Liabilities:Payable (positive amount): Reduces what the organization owes the user (they get credited back)

Existing Example

There is already a correctly formatted refund in the ledger:

Entry ID: f1a51d013ab14757
Description: "EDF Refund"
Amount: 396.72 EUR credited back

Notes

If the refund is linked to a specific original expense, consider using ^exp-{original-entry-id} to connect them in Fava
The #expense-entry tag is appropriate since it's an expense adjustment
Alternatively, a dedicated #refund-entry tag could be introduced if we want to filter refunds separately

## Summary We need to formally add a **Refund** entry type to our accounting specification. Refunds occur when a vendor/service provider credits back an overcharge. ## Proposed Entry Type | Entry Type | Links | Tags | Key Metadata | |------------|-------|------|--------------| | Refund | `^exp-{original-entry-id}`, `^castle-{entry-id}` | `#expense-entry` | user-id, entry-id, source | ## Transaction Format ```beancount 2025-10-31 * "Vendor Refund" #expense-entry ^castle-{entry-id} ^exp-{entry-id} source: "castle-api" entry-id: "{entry-id}" Liabilities:Payable:User-xxxxx +XX.XX EUR @@ XXXXX SATS Expenses:Category -XX.XX EUR @@ XXXXX SATS ``` ## Accounting Logic - **Credit to Expenses** (negative amount): Reduces the original expense since the amount was overcharged - **Debit to Liabilities:Payable** (positive amount): Reduces what the organization owes the user (they get credited back) ## Existing Example There is already a correctly formatted refund in the ledger: - Entry ID: `f1a51d013ab14757` - Description: "EDF Refund" - Amount: 396.72 EUR credited back ## Notes - If the refund is linked to a specific original expense, consider using `^exp-{original-entry-id}` to connect them in Fava - The `#expense-entry` tag is appropriate since it's an expense adjustment - Alternatively, a dedicated `#refund-entry` tag could be introduced if we want to filter refunds separately

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: aiolabs/castle#2

No description provided.

Rows
Columns