Create a transaction

POST https://app.speybooks.com/api/v1/transactions/

Creates a new manual double-entry transaction. The transaction must have at least two lines and the sum of all line amounts must equal zero (debits = credits). This constraint is validated before any database writes occur.

Line Fields

Each line requires:

  • accountId — prefixed account ID (e.g. acc_4000)
  • amount — integer in minor units (pence). Positive = debit, negative = credit

Optional per-line fields:

  • vatRate — integer 0–100 (e.g. 20 for 20% VAT)
  • vatTreatment — inclusive, exclusive, or none
  • contactId — prefixed contact ID for contact-level reporting
  • description — line-level description, max 500 characters

VAT Calculation

When vatRate and vatTreatment are provided (and treatment is not none), the API computes the vatAmount for tax reporting:

  • exclusive — VAT is on top: vatAmount = |amount| × rate
  • inclusive — VAT is within: vatAmount = |amount| − (|amount| / (1 + rate))

This is a per-line tax annotation stored for HMRC reporting. It does not inject balancing lines, modify the journal total, or alter any other line. The API consumer must still send all lines required to balance the journal — including the explicit VAT account line.

Status

Defaults to posted. Pass status: "draft" to create an editable draft excluded from balances and reports.

Validation

All referenced account IDs must exist and be active within the organisation. The balance constraint (∑amounts = 0) is absolute — the API returns 400 if violated.

Error responses:

  • 400 — lines do not balance (∑amounts ≠ 0)
  • 400 — fewer than 2 lines
  • 400 — invalid or inactive account ID
  • 400 — invalid contact ID
  • 400 — metadata validation failure (reserved keys, exceeded limits)

Body parameters

date string required
Transaction date (YYYY-MM-DD).
date
description string required
Transaction description (1-500 characters).
lines array<object> required
Journal lines. Minimum 2 required. Sum of all amounts must equal zero.
min items: 2
Show child parameters
accountId string required
Account ID (e.g. acc_1200). Must be an active account.
amount integer required
Amount in pence. Positive = debit, negative = credit. E.g. 10000 for a £100.00 debit.
contactId string optional
Optional contact ID (e.g. cont_3) to associate with this line.
description string optional
Optional per-line description (max 500 characters).
vatRate integer optional
VAT rate as integer percentage (e.g. 20). Optional.
vatTreatment string optional
VAT calculation method. none = no VAT, inclusive = VAT included in amount, exclusive = VAT added on top.
noneinclusiveexclusive
metadata object optional
Arbitrary key-value pairs (max 50 keys, 500 chars per value).
reference string optional
Optional external reference (max 100 characters).
status string optional
Transaction status. Defaults to posted.
draftposted

Response

201 Transaction created. Returns the prefixed transaction ID.
Show response fields
id string

Error codes

400 Validation error, unbalanced transaction, or invalid account/contact ID.