Record a payment

POSThttps://app.speybooks.com/api/v1/invoices/{id}/payment

Records a payment against an invoice. The amount is an integer in PENCE: £50.00 is sent as 5000.

Payments apply to issued, open invoices only (status sent or partial). Paying a draft is rejected, with guidance to issue the invoice first; paying a terminal invoice is rejected; a missing invoice is reported as not found.

The invoice status updates automatically: paid when cumulative payments reach the invoice total, partial otherwise. These statuses are payment-derived and cannot be set via the status endpoint. Overpayment is rejected; the sum of payments can never exceed the invoice total (enforced at the database).

In the response, newStatus is the status after this payment, amountRecorded is the amount recorded by this request, and amountPaid is the cumulative total paid against the invoice, both in pence.

To reverse a recorded payment, use POST /:id/payment/reverse (reverseInvoicePayment): a full reversal that returns amount_paid to zero and reopens the invoice to sent.

Path parameters

idstringrequired

Body parameters

amountintegerrequired
min: 1
datestringoptional
date

Response

200Default Response
Show response fields
amountPaidinteger
amountRecordedinteger
newStatusstring

Error codes

400Default Response
404Invoice not found.