Create a transaction

POSThttps://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 to 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 a draft that is 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. Posting to a control account from a source it does not permit is rejected with a message naming the account and its permitted sources.

Body parameters

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

Response

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

Error codes

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