Manual Booking

• Introduction
  • Transaction Types
• Create and update manual bookings
  • Import Source
  • Automatic Behaviors
• Resolve a conversion rate
• Delete a manual booking

Introduction

Manual bookings allow you to create custom journal transactions for accounting purposes. Unlike system-generated transactions from invoices or expenses, manual bookings give you direct control over journal entries while maintaining double-entry bookkeeping principles.

Each manual booking creates a journal transaction with multiple entries that record specific debits and credits to individual accounts. The system ensures all entries balance (total debits equal total credits) and maintains accounting integrity.

Transaction Types

Type	Description
Single	Simple transaction with exactly two journal entries (one debit, one credit)
Compound	Complex transaction with more than two journal entries

Create and update manual bookings

post

/journal

Create or update manual bookings with proper double-entry validation. Supports both single transactions (2 entries) and compound transactions (multiple entries).

Attribute (* required)	Type	Description
id	String?	ID of existing booking to update (omit for new transaction)
date *	Date	Transaction posting date (must be within open fiscal year)
message *	String	Transaction description (max 255 chars)
currency	String?	Booking currency code (e.g. EUR, USD) - defaults to CHF. Foreign currencies must be configured for the organization
conversion_rate	Number?	Per-unit conversion rate to CHF (e.g. 0.9328 for 1 EUR = 0.9328 CHF). Omit to use the automatic rate (organization rate, falling back to the official BAZG monthly rate)
type	String?	single or compound. Optional - the mode is inferred from whether entries is present. When given, it enforces the matching field set
Single Transaction Mode
debit_account_id *	String	Account ID for debit entry
credit_account_id *	String	Account ID for credit entry
amount *	Number	Transaction amount in the booking currency (must be > 0)
vat_rate_id	String?	VAT Rate ID
Compound Transaction Mode
entries *	Array	Array of journal entries (min 2 entries)
entries.*.account_id *	String	Account ID
entries.*.debit_amount	Number?	Debit amount (≥ 0)
entries.*.credit_amount	Number?	Credit amount (≥ 0)
entries.*.vat_rate_id	String?	VAT Rate ID
entries.*.description	String?	Entry-specific description (max 255 chars)
entries.*.currency	String?	Entry currency - defaults to the booking currency
File Attachment
file	File?	Supporting document (max 10MB, PDF/images/Office docs)

Validation Rules

• Single mode: Requires debit_account_id, credit_account_id, and amount
• Compound mode: Requires entries array with balanced debits/credits
• Exactly one mode must be used: a request without entries must contain the single-mode fields, and vice versa. A request providing neither is rejected with 422 (not silently accepted)
• type: single additionally prohibits entries; type: compound additionally requires entries
• Each entry must have either debit OR credit amount, not both
• Sum of debit amounts must equal sum of credit amounts
• Transaction date must be within an open fiscal year
• Accounts must exist and be different for single transactions
• A foreign currency must be configured as a currency of the organization

Foreign Currency Bookings

Amounts are entered in the booking currency and balanced in that currency. On posting, every journal entry is converted to CHF using the conversion_rate (or the automatic rate for the posting date). The original amount and rate stay stored on each journal entry. Any leftover CHF rounding difference from the per-entry conversion is booked automatically to the organization's financial income/expenses account (default 6900/6950).

VAT Handling

The system automatically determines which side (debit/credit) to apply VAT based on account types:

• Revenue transactions: VAT on revenue side
• Expense transactions: VAT on expense side
• Asset transactions: Special handling for fixed assets (accounts 1400-1999)

Single Transaction Example

{
    "date": "2024-03-15",
    "message": "Office equipment purchase",
    "debit_account_id": "acc_equipment_id",
    "credit_account_id": "acc_bank_id",
    "amount": 1080.0,
    "vat_rate_id": "vat_77_id",
    "currency": "CHF"
}

Compound Transaction Example

{
    "date": "2024-03-15",
    "message": "Multi-account expense allocation",
    "entries": [
        {
            "account_id": "acc_office_supplies",
            "debit_amount": 500.0,
            "description": "Office supplies",
            "vat_rate_id": "vat_77_id"
        },
        {
            "account_id": "acc_marketing",
            "debit_amount": 300.0,
            "description": "Marketing materials"
        },
        {
            "account_id": "acc_bank",
            "credit_amount": 800.0
        }
    ]
}

Update Transaction Example

{
    "id": "existing_booking_id",
    "date": "2024-03-16",
    "message": "Updated: Office equipment purchase",
    "debit_account_id": "acc_equipment_id",
    "credit_account_id": "acc_bank_id",
    "amount": 1200.0,
    "file": "[uploaded file]"
}

Import Source

Manual bookings created by an integration or import carry a source value inside custom_fields (e.g. stripe, lightspeed, shopify, bexio, banana, abasalary, selectline, csv_import). The resource exposes this as a read-only import_source attribute; older Bexio and Banana imports without a source value are derived from their bexio_id/banana_id custom field. Updating a booking never removes its custom fields, so provenance survives manual edits.

Automatic Behaviors

The system automatically handles several aspects of manual booking management:

Transaction Numbering

• Automatic numbering: New transactions receive sequential numbers (number_sequence) and formatted numbers (number_full)
• Number format: Uses system-defined prefix + sequence number (e.g., "TX-1001")

Fiscal Year Management

• Auto-creation: Missing fiscal years are automatically created when transactions are posted
• Validation: Transaction dates must fall within open (non-closed) fiscal years
• Updates blocked: Transactions cannot be updated if their fiscal year is closed
• Deletions blocked: Transactions cannot be deleted if their fiscal year is closed

VAT Period Management

• Auto-creation: VAT periods are automatically created for transaction dates when missing
• Swiss compliance: Ensures proper VAT reporting period structure

User Attribution

• Member tracking: Transactions are automatically attributed to the current user's member record
• Audit trail: Maintains who created/modified each transaction

Manual Booking Cleanup

• Cascade deletion: When deleting manual booking transactions, the associated manual booking document is also removed

Fiscal Year Restrictions

• Transactions in closed fiscal years cannot be updated or deleted
• The system will throw a FiscalYearClosedException if these operations are attempted
• Always verify fiscal year status before attempting modifications

Resolve a conversion rate

get

/journal/conversion-rate

Resolves the conversion rate to CHF for a currency on a given date, using the organization's own exchange rates first and falling back to the official BAZG monthly average rate. Useful for prefilling the conversion_rate of a foreign currency booking.

Parameter (* required)	Type	Description
currency *	String	Currency code (e.g. EUR, JPY)
date	Date?	Date to resolve the rate for - defaults to today

Example response

{
    "currency": "JPY",
    "rate": 0.00585,
    "units": 100,
    "display_rate": 0.585
}

rate is the per-unit rate (what conversion_rate expects). units reflects how the currency is officially quoted (1, 100 or 1000) and display_rate is the rate for that quantity (e.g. 100 JPY = 0.585 CHF). rate is null when no rate is available for the currency.

Delete a manual booking

delete

/journal_transaction/{id}

Transaction Deletion Restrictions

• Locked transactions cannot be deleted
• Transactions from closed fiscal years cannot be deleted (system enforced)
• Manual booking transactions will also delete their associated document
• Consider the impact on financial reports before deletion

Example response

// HTTP 204 No Content