Journal Transaction

• Introduction
  • Transaction Types
  • Document Types
• Allowed query parameters
• Retrieve a journal transaction
• List journal transactions

Introduction

Journal transactions are the core bookkeeping entries in the accounting system, representing the double-entry bookkeeping principle where each transaction affects at least two accounts. They form the backbone of the Swiss KMU accounting structure.

Each journal transaction contains multiple journal entries that record the specific debits and credits to individual accounts. The transaction serves as the container that groups related entries together and ensures they balance (total debits equal total credits). This structure maintains the integrity of double-entry bookkeeping while providing a clear audit trail for each business event.

Manual Bookings

To create, update, delete, or reverse journal transactions through the API, use the Manual Booking resource. Direct manipulation of journal transactions via the API is not allowed to maintain 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

Document Types

Journal transactions can be linked to various source documents:

Document Type	Description
invoice	Sales invoices
invoice_payment	Invoice payment records
expense	Expense records
expense_payment	Expense payment records
bank_transaction	Bank transaction records
customer_transaction	Customer transaction records
manual_booking	Manual accounting entries

Allowed query parameters

Filters

Filter	Type	Description
number	String	Exact match on transaction number
document_number	String	Exact match on document number
document_type	String	Filter by document type: invoice, invoice_payment, expense, expense_payment, bank_transaction, customer_transaction, manual_booking
search	String	Full-text search across transaction data
date_range	String	Date range filter (format: YYYY-MM-DD,YYYY-MM-DD)
amount_range	String/Array	Amount range filter
includes_account	String/Integer	Filter transactions that include a specific account
includes_vat_rate	String	Filter transactions that include a specific VAT rate
source	String	Filter manual bookings by import source (e.g. stripe, lightspeed, shopify, bexio, banana, abasalary, selectline, csv_import)
member	String	Filter by member ID

Sorting

posted_at, number_sequence, document_number

Includes

document, entries.account, entries.vatRate, fiscalYear, media, member.user.media

Appends

summary - Transaction summary data (requires appropriate permissions)

Retrieve a journal transaction

get

/journal_transaction/{id}

Example response

// HTTP 200 OK
{
    "id": "v7rnRjBn9o",
    "number": "TX-1001",
    "posted_at": "2024-03-15",
    "document": {
        "id": "abc123",
        "type": "invoice",
        "number": "INV-2024-001"
    },
    "document_id": "abc123",
    "document_type": "invoice",
    "document_number": "INV-2024-001",
    "fiscal_year": {
        "id": "fyxyz789",
        "name": "2024",
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
    },
    "description": "Sales invoice payment",
    "entries": [
        {
            "id": "entry1",
            "account": {
                "id": "acc1",
                "number": "1020",
                "name": "Bank Account"
            },
            "debit_amount": 1080.0,
            "credit_amount": 0,
            "type": "debit",
            "currency": "CHF"
        },
        {
            "id": "entry2",
            "account": {
                "id": "acc2",
                "number": "3400",
                "name": "Sales Revenue"
            },
            "debit_amount": 0,
            "credit_amount": 1000.0,
            "type": "credit",
            "currency": "CHF"
        }
    ],
    "type": "single",
    "amount": 1080.0,
    "currency": "CHF",
    "original_amount": 1080.0,
    "is_locked": false,
    "is_future": false,
    "debit_account": {
        "id": "acc1",
        "number": "1020",
        "name": "Bank Account"
    },
    "credit_account": {
        "id": "acc2",
        "number": "3400",
        "name": "Sales Revenue"
    },
    "debit_vat_rate_id": null,
    "credit_vat_rate_id": "vat123",
    "member": {
        "id": "mem1",
        "name": "John Doe"
    },
    "reverses": null,
    "reversed_by": null,
    "can_delete": false,
    "can_edit_in_place": false,
    "edit_requires_reversal": false,
    "can_reverse": false,
    "default_reversal_date": null
}

Reversal and immutability fields

The following fields are populated for manual bookings. For all other transactions they are null (false for the booleans). They are only returned by GET /journal_transaction, GET /journal_transaction/{id}, GET /journal_entry and GET /journal_entry/{id} with include=transaction (on the nested transaction), the reverse response and the transaction in the POST /journal response.

Field	Type	Description
reverses	Object?	{id, number} of the original booking when this transaction is a reversal, otherwise null
reversed_by	Object?	{id, number} of the reversal booking when this transaction was reversed, otherwise null
can_delete	Boolean	Whether the booking can be deleted. false for older bookings while the immutable journal is enabled, and for bookings that were already reversed
can_edit_in_place	Boolean	Whether the booking can be edited in place. false for older bookings while the immutable journal is enabled, and for reversed bookings
edit_requires_reversal	Boolean	true when updating the booking via POST /journal with id reverses it and creates a new booking: the immutable journal is enabled, the booking was created before today and it was not reversed
can_reverse	Boolean	Whether the booking can be reversed. true also in a closed fiscal year (the reversal is then posted on the first open date), false for bookings that were already reversed
default_reversal_date	Date?	Date (YYYY-MM-DD) a reversal gets when no date is given: the booking date if its fiscal year and VAT period are open, otherwise the first open date. null for bookings that were already reversed

List journal transactions

get

/journal_transaction

The list endpoint accepts the same parameters as in Retrieve a journal transaction and returns a paginated array of the same transaction object in the data property.

Read more about Pagination, Filtering, Sorting and Includes on the Introduction page.

Example response

// HTTP 200 OK
{
    "data": [
        {
            // transaction object
        }
    ],
    "links": {
        "first": "https://api.example.com/journal_transaction?page=1",
        "last": "https://api.example.com/journal_transaction?page=10",
        "prev": null,
        "next": "https://api.example.com/journal_transaction?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "per_page": 15,
        "to": 15,
        "total": 150
    },
    "summary": {
        "total": 125430.5
    }
}