Update organisation settings

PUT https://app.speybooks.com/api/v1/organisation/settings

Update operational settings that govern platform behaviour. Settings are split across three storage locations, all updated atomically within a savepoint:

  • Organisation JSONB — currency, vatRegistered, vatScheme, vatFlatRatePercent, fiscalYearStart
  • Invoice settings — invoicePrefix, invoiceNextNumber, invoiceDefaultTerms, invoiceDefaultNotes
  • Quote settings — quotePrefix, quoteNextNumber, quoteDefaultTerms, quoteDefaultNotes, quoteValidityDays

Only include fields you want to change. The fiscal year start uses MM-DD format (e.g. "04-06" for 6 April, the UK tax year).

Triggers an ORGANISATION_SETTINGS_UPDATED audit log entry.

Body parameters

currency string optional
ISO 4217 currency code (e.g. GBP, EUR). 3 characters.
fiscalYearStart string optional
Fiscal year start as MM-DD (e.g. 04-06 for UK tax year).
invoiceDefaultNotes string optional
Default notes text for new invoices.
invoiceDefaultTerms string optional
Default payment terms text for new invoices.
invoiceNextNumber integer optional
Next invoice auto-number.
invoicePrefix string optional
Invoice number prefix (max 10 characters, e.g. INV).
quoteDefaultNotes string optional
Default notes text for new quotes.
quoteDefaultTerms string optional
Default terms text for new quotes.
quoteNextNumber integer optional
Next quote auto-number.
quotePrefix string optional
Quote number prefix (max 10 characters, e.g. QTE).
quoteValidityDays integer optional
Default quote validity period in days (1-365).
vatFlatRatePercent number optional nullable
Flat rate VAT percentage (0-100). Only relevant when vatScheme is flat_rate.
vatRegistered boolean optional
Whether the organisation is VAT registered.
vatScheme string optional
VAT accounting scheme.
not_registeredstandardflat_rate

Response

200 Settings updated successfully.
Show response fields
updated boolean

Error codes

400 Validation error in settings data.