Skip to main content

Core Concepts: How SpeyBooks Works

This page explains how accounting data flows through SpeyBooks — from real-world business events to financial reports.

SpeyBooks models accounting as a deterministic pipeline, not a collection of UI actions.

The accounting flow​

Contact → Business Event → Transaction → Accounts → Reports

Each stage has a single responsibility:

  1. Contacts represent customers and suppliers
  2. Business events (invoices, expenses, payments) describe what happened
  3. Transactions record the double-entry debits and credits
  4. Accounts accumulate balances from transactions
  5. Reports are derived from the ledger in real time

Nothing bypasses this flow.

Worked example: selling consulting services​

This example shows what happens internally when you invoice a customer and receive payment.

1. Create a contact​

Create a customer contact.

POST /v1/contacts
{
  "contactType": "customer",
  "name": "Acme Corporation"
}

Result: cont_17

2. Create and send an invoice​

Create an invoice for consulting services.

POST /v1/invoices
{
  "contactId": "cont_17",
  "items": [
    {
      "description": "Consulting — January",
      "quantity": 10,
      "unitPrice": 10000,
      "vatRate": "standard"
    }
  ]
}

Result: inv_42 — Total: £1,200.00 (including VAT)

3. SpeyBooks creates the transaction automatically​

When the invoice is issued, SpeyBooks generates a double-entry transaction behind the scenes.

{
  "id": "txn_52",
  "description": "Sales invoice INV-2026-0001",
  "lines": [
    { "accountId": "acc_1100", "amount": 120000 },
    { "accountId": "acc_4000", "amount": -100000 },
    { "accountId": "acc_2200", "amount": -20000 }
  ]
}

Ledger effect:

AccountDebitCreditMeaning
Accounts Receivable (1100)£1,200Customer owes you
Sales (4000)£1,000Revenue earned
VAT Output (2200)£200VAT owed to HMRC
Invariant

Debits and credits always balance. This is enforced at the API level.

4. Record the payment​

When the customer pays the invoice:

POST /v1/invoices/inv_42/payments
{
  "amount": 120000,
  "date": "2026-02-15",
  "method": "bank_transfer"
}

SpeyBooks creates a second transaction:

AccountDebitCreditMeaning
Bank (1200)£1,200Funds received
Accounts Receivable (1100)£1,200Customer balance cleared

The invoice is now fully settled.

5. See the impact in reports​

Because reports are derived from the ledger, the effects are visible immediately.

Profit & Loss (for the period):

  • Revenue: £1,000
  • Net profit: £1,000

Balance Sheet (after payment):

  • Bank: +£1,200
  • VAT payable: £200

VAT Return:

  • Box 1 (VAT on sales): £200
  • Box 6 (Total sales excl. VAT): £1,000
note

No reports are manually updated. They are computed directly from the ledger state.

Key principles​

Every transaction balances​

Debits always equal credits. Unbalanced transactions are rejected by the API.

Business events create transactions​

You do not manually post journals for routine activity. Create invoices, record payments, import bank statements — SpeyBooks generates the accounting entries automatically.

Manual journals exist for exceptions​

Year-end adjustments, corrections, and non-standard entries are created explicitly via the Transactions API.

Reports are derived, not stored​

Reports are generated from the ledger at query time. Nothing is pre-calculated, cached, or hidden.