SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Finance API contracts

Invoice, payment and settlement contracts for integrators — money serialisation, idempotency, payment and refund payloads, write-offs, financial postings, settlement allocation, provider refunds, chargebacks, legal debit corrections and revaluation.

Overview

This is the contract reference behind Invoicing & Payments and Payments. It describes what the finance endpoints accept and return, and the ledger rules every financial source follows. Operator commands for reconciliation and repair are in Finance operations.

Event-sourced finance records

Invoices, payments, and credit notes are Verbs event streams with projected read models — the same pattern as rentals. Reads hit the projection; writes fire events and dual-write the read model.

Money in responses

All monetary fields serialise as decimal strings (e.g. "125.50"), not floats or raw integers. Values are stored in integer minor units internally. Tax follows the framework's ex-tax model with tax computed finally and grouped by tax type.

Invoice line responses include the stored catalogue_item_price_id and rate_specification_id as nullable integer identities. REST invoice reads and the curated MCP invoice reader expose the captured invoice-item values without looking up current catalogue prices or specifications. Prior, manual and synthetic lines without a captured identity return null; these fields do not recalculate prices or replace the accepted pricing manifest.

The read API keeps the existing payment fields and adds currency_code, base_currency_code, invoice_aggregate_version, reference_origin, settlement_id and allocation_id. The amount uses the owning invoice's currency exponent, including JPY (zero decimals) and KWD (three decimals). The version belongs to the invoice, not the payment; it is not an idempotency key. Settlement/allocation IDs are null when no persisted link exists. These IDs do not include another invoice's allocations or provider payloads. paid_at is the effective date of this payment row, not the time when the entire invoice became paid.

Rental checkout requests

POST /api/v1/rentals/{rental}/invoices defaults type to standard. Choose a full remaining checkout by omitting lines, amount_fixed and amount_percentage, or supply exactly one of those fields. A deposit requires type: "deposit" and exactly one amount field. A proforma uses type: "proforma" and accepts no partial selection.

Checkout accepts only the documented fields: type, lines, amount_fixed, amount_percentage, notes, reference, tag_list, expected_version and idempotency_key. Unknown fields return 422, including amount_percetage and line. Each rental_line_id may appear only once in lines, even when repeated entries request different quantities; duplicates return 422 before invoice creation.

Inactive selection fields may be omitted or explicitly null. Empty arrays in those fields return 422 before an invoice or checkout receipt is created, including lines: [] on deposits and amount fields set to [] on proformas.

Percentages are decimal strings greater than zero and at most 100. Per-line quantities are decimal strings from 0.01 through 99999999.999999, with at most six decimal places. Numeric JSON values, exponent notation, empty selections and repeated rental line identifiers are rejected. Fixed amounts are positive integer minor units. Partial standard checkout requires an Idempotency-Key header or an idempotency_key body field; supply the same value when using both. Current remaining amounts and quantities are checked when the invoice is generated.

Idempotency

Financial POST endpoints honour the Idempotency-Key header to prevent duplicate side effects on retry. Scoped to the bearer token; replays stored 2xx/422 responses for up to 24 hours. Applies to checkout, payment recording, and refunds.

Recording payments and refunds

API conventions, API versioning and MCP apply to finance endpoints.

Payment and operator-refund input is a positive integer amount in minor units of the invoice currency. Refund output is signed. A minimal payment payload:

{
    "amount": 12500,
    "payment_method": "bank_transfer",
    "reference": "PAY-001"
}

Use the refund route for refunds; never send a negative amount. Payment responses return a signed decimal string with the invoice currency, any settlement and allocation identity, and the invoice aggregate version. Missing historical identities are returned as null.

The allocate-settlement MCP tool calls api.v1.invoices.settlement_allocations.store and requires payments:write and an authorised staff user. Retry with the same idempotency key, target, amount and reason.

Cancelling a posted invoice uses the existing void/credit permissions and an expected-version check. It keeps the original posting and records the remaining credit. Cancellation does not refund cash and does not make the invoice eligible for billing-run undo.

The full API schema is in the API reference.

Write-offs and reversals

Write-off commands require an authorised staff actor, reason and idempotency key. The write-off and its event are saved together atomically. An exact retry returns the original adjustment and captured outcome, including after a later command; reusing its key with a different actor, amount, reason, effective date or original reversal target is refused. Current permission and warehouse scope still apply. New write-offs need a positive ceiling for the invoice currency; zero or an absent entry disables them. A reversal uses the ceiling that applied to the original write-off. Write-offs are dated the current UTC day; backdating is not yet available.

REST exposes POST /api/v1/invoices/{invoice}/write_offs and POST /api/v1/invoices/{invoice}/write_off_reversals. Both require invoices:write, the invoices.write-off permission, invoice warehouse access and an Idempotency-Key header; a body key, if supplied, must match the header. The curated MCP tools are post-invoice-write-off and reverse-invoice-write-off, which require an explicit idempotency_key. The invoice page has post and reversal forms and a permission-gated, paged list of reasons. Operator decimal amounts must convert exactly to invoice-currency minor units; extra digits are refused, not rounded.

The response contains data.adjustment (schema version 1): integer transaction/base minor units, named currencies, source identity as a string, original/reversal identity, actor, reason and the resulting balances. data.aggregate_version identifies the invoice version. Retrying with the same key returns the original outcome, even after later commands.

Financial postings

Issuing a standard posting invoice (is_posting true) records a balanced financial posting: receivables, invoiced turnover and tax control, in both the transaction currency and the base currency. If rounding the base amounts separately leaves a difference, it is shown as an explicit base-only rounding line; the legal document amounts never change. Invoiced turnover is not the same as earned rental revenue. Drafts, deposit requests and pro-forma documents do not post.

Postings are also recorded for:

  • Credit notes when they take effect (issued immediately, or a draft applied). A partial credit reverses the original turnover and tax at the invoice's frozen rate, and never reverses more base receivable than the original invoice.
  • Verified provider receipts — debit provider clearing, credit unapplied funds for the full gross amount. A receipt is not tied to an invoice, account or warehouse until it is allocated. If the currency or conversion cannot be resolved, the receipt is kept with an exception and no posting is made.
  • Provider allocations — debit unapplied funds, credit receivables. A base difference posts to rounding when rates match, or realized_fx when they differ.
  • Positive manual payments — debit manual_cash_control, credit receivables. Cash converts at the recorded payment date; if that conversion cannot be resolved, the payment is refused.
  • Operator-recorded refunds — credit manual_cash_control, debit receivables. A refund must name its original funded payment (original_payment_id) when more than one payment on the invoice has refundable funds, and cannot exceed the original payment's remaining amount.

Each payment has at most one posting. Postings are immutable: a correction is a new financial document, never an edit. confirmation_source: operator_recorded on a refund is the operator's statement that money was returned; Signals does not send a request to the payment provider. Refunding a provider-funded payment keeps its original allocation link but does not return that amount to unapplied funds.

The invoice carries written_off_total, the net non-cash write-off value in invoice currency (zero by default). Payment, refund and credit balance calculations subtract it separately.

The read-only finance integrity report (schema version 17) counts captured sources missing a posting (captured_financial_sources_without_postings), postings that conflict with their source (financial_posting_contract_conflicts) and write-off mismatches (invoice_write_off_fact_mismatches). It never writes or repairs postings, and its alerts contain only tenant, code and count. Invoice rehearsal can add missing posting rows but refuses to overwrite or delete existing ones.

Balanced source postings

A supported financial source event owns one immutable posting with ordered debit and credit lines. Transaction minor units balance independently of base minor units; balances from different currencies are never added together. The posting preserves the original currency, precision, rate/date, financial dimensions and tax identities. Replay verifies the captured source instead of reading a current conversion or tax value. A provider payment points to its allocation posting; it does not create a second cash posting.

Source Accounting policy and account signs
Issued invoice operational-invoice-issue-v1: receivables debit, invoiced turnover and tax control credit. Historical operational-v1 remains explicitly supported.
Effective credit operational-credit-effect-v1 reverses original receivable, turnover and tax legs. A proposed draft has no posting; later application posts once.
Manual payment / original-funded refund operational-manual-payment-v1 / operational-operator-refund-v1: manual cash control debit and receivable credit for payment; the original payment legs reverse for a refund. Frozen base amounts can require realized FX or rounding legs.
Verified receipt operational-provider-receipt-v1: provider clearing debit and unapplied funds credit. Receipt and invoice conversions are kept separate.
Allocation operational-provider-allocation-v1: unapplied funds debit and receivable credit, preserving before/after cash and base balance pointers plus any captured FX/rounding legs.
Allocation correction operational-allocation-reversal-v1: exact inverse of the original allocation, preserving the original receipt and payment. This is a non-cash correction, not a provider refund.
Write-off / reversal operational-write-off-v1 / operational-write-off-reversal-v1: write-off expense debit and receivable credit; a reversal uses the exact inverse.

Carrying manual payments keep their operational-carrying-manual-payment-v1 or operational-carrying-manual-payment-v2 policy.

An issued cancellation credits the eligible remaining original amount; its cancellation marker adds no duplicate posting. Voiding an effective issued invoice or credit is refused. Account-merge financial effects are provenance referencing the original issue posting, not another ledger entry. Verified chargeback posting implementation and acceptance belong to the shared chargeback source; no refund or generic negative-payment alias substitutes for it.

Allocation reversal retains account IDs, merge lineage and participant identity, authority and the caller's explicit invoice version. After waiting for another invoice's allocation, it captures current financial facts under the held owners rather than rejecting an unrelated pre-lock account credit-clock change. Reallocating restored cash still requires its admitted carrying policy; this correction does not waive that guard. An identical completed command is inert; another reversal command cannot reverse the same allocation twice.

PostgreSQL enforces line direction, immutability and deferred complete balance with constraints and triggers. SQLite has no database-level balance or immutability enforcement; its projector validates supported complete frozen facts before writing and detects changed rows when verifying them.

Document currencies are limited to the supported set. KWD document creation refuses with invoice_document_currency_unsupported before writes; configuring EUR metadata to scale three still fails ISO-scale validation before posting. Three-decimal currencies are not yet supported for documents. Zero-decimal JPY and two-decimal sources keep their original units.

Operator allocation is available through the invoice's REST route, generic MCP, curated allocate-settlement and Volt action. Allocation reversal is a staff command on PostgreSQL installations; it is not yet available through the API or the UI. The invoice page has no refund form; refunds are recorded through REST or generic MCP and must name their original payment.

New invoice snapshots capture each original revenue-account identity as a soft reference. Turnover lines group only those frozen identities; deterministic cumulative base conversion preserves the exact subtotal base amount. Partial credits and the remaining credit inverse retain those groups and exhaust their original transaction and base amounts. A newly captured unassigned line is explicit; historical missing attribution is unavailable and cannot be rebuilt from current catalogue or rental groups. Replay of a recorded source keeps its original conversion contract. A draft with uncaptured group evidence refuses issue with invoice_revenue_account_missing; replace its affected draft lines through the existing draft editor before issuing. An issued schema-one invoice can still be credited or cancelled against its proven original unassigned turnover leg. Missing original posting evidence remains refused. PostgreSQL write-off admission accepts original conversion schemas one and two without relaxing its source, amount or approval checks.

Settlement allocation and cash conservation

Reversing an allocation restores its original transaction and base cash amounts. Reusing that restored cash on another permitted issued invoice keeps the receipt, reversal and preceding allocation identities. Successive allocations consume the captured restored basis with cumulative HALF_UP rounding and assign the final base residue to the last allocation; current exchange rates do not replace that basis. This creates another allocation and invoice payment, without recording another receipt or changing the original invoice. An original-funded operator refund does not replenish unapplied receipt cash. Later allocations verify the refund’s ordered original funding and recorded payment, then continue consuming the same captured basis and final residue.

Invoice projection rehearsal retains the immutable allocation, payment and posting dependencies of the same carrying settlement across invoices. It reconstructs the selected invoice's posting from its recorded source and refuses missing or contradictory components. Each restored-cash allocation and every preceding allocation must retain its own provider payment with the original invoice, exact minor amount, provider reference and reference origin. The allocation must also retain its recorded receipt, invoice, payment, base currency, amount, operator key, actor, reason and timestamp. A retained pre-reversal allocation has the same requirement as an prior restored-cash allocation. Safe payment notes and effective-date corrections do not replace these financial identities. Qualified frozen replay and metadata repair do not establish a complete rebuild with all settlement projections absent, concurrent allocation ordering, provider refund outcomes or legal debit adjustment support.

Keep the integer minor amount with its named transaction currency and exponent: 100 JPY minor units means JPY 100, while 100 KWD minor units means KWD 0.100. Base amounts need their own named currency and stored conversion evidence. A manual unlinked row has no invented settlement, allocation or historical base denomination. Retrying a captured command returns its retained identity and outcome; it does not establish that the settlement's entire gross amount has been allocated.

Allocation requires the original settlement and invoice to have the same account and exactly matching captured transaction and base currency codes. A merged account alias does not transfer the original cash debtor to its canonical successor. Missing, differently cased or conflicting currency evidence is refused; cross-currency application requires explicit realised-FX, currency-leg and residual-rounding rules. Changing today's base currency or exchange rate cannot supply those missing historical facts.

Let G be the original verified receipt, A its effective allocated principal, and R the cash returned from those allocations by recorded refunds or verified chargebacks. All three use integer minor units in the original transaction currency. The retained partition is G − R = (A − R) + (G − A): net cash equals funded applied cash plus original unapplied cash. A cash return does not replenish the original unapplied balance. Combined refunds and chargebacks cannot exceed the remaining original funded principal. A valid allocation reversal can release unreturned allocation principal; it cannot release cash already returned by either family.

A staff command (not available through the API or UI) records a verified chargeback against one original verified provider allocation and its recorded payment and posting. It requires an authorised actor, explicit original currencies, a verification reference, reason and command key. Its immutable receipt captures the original cash, receivable and paid-base amounts separately; partial returns use cumulative rounding against each original basis, so a final return consumes the exact retained remainder without a current rate lookup. There is no chargeback REST or MCP endpoint, and this command neither initiates a provider debit nor interprets a chargeback-shaped webhook as a payment or refund.

REST and MCP allocation refusals preserve their existing authorisation and warehouse boundaries. An unsupported currency application returns HTTP 422 with settlement_allocation_currency_unsupported; a different or missing original debtor returns settlement_allocation_account_mismatch. An identical completed allocation command key is inert; a changed request returns settlement_allocation_idempotency_conflict. These refusals do not create a payment, allocation or posting. Historical conflicting funding requires explicit reconciliation rather than relabelling original cash or inventing conversion evidence.

A distinct pending chargeback records its provider dispute identity, selected original settlement/allocation and authorised actor without changing cash or reserving principal. Confirmation must match that pending source's invoice, original payment, amount and currencies; a second confirmation refuses, while an identical command retry is inert. Confirmed refunds and chargebacks share the original principal limit, including outstanding provider-refund reservations. Pending and confirmed facts fold from their recorded sources without consulting current prices or rates.

A verified provider win uses a separate restoration event against one confirmed chargeback. It exactly reverses that loss posting, including each original cash, receivable, FX and rounding leg, and records a positive chargeback_restored payment. It does not create a receipt, allocation or a refund. The confirmed loss and original settlement/allocation remain immutable; identical win retries are inert, conflicting wins refuse. Restored cash does not renew the original refund/chargeback principal limit.

With W as cash restored by verified wins, the retained partition becomes G − R + W = (A − R + W) + (G − A). Return capacity remains bounded by A − R, separately from net retained cash. Pending, confirmed and restored outcomes replay from captured original facts without current rate lookup. These staff commands neither contact a provider nor interpret unauthenticated outcomes.

Provider refunds

Drivers may implement ProviderRefundWebhookDriver::verifyRefundWebhook() to decode authenticated refund outcomes separately from checkout completions. Stripe verifies the raw body against the configured signing secret and retains the event, merchant, mode, refund and original PaymentIntent identities, exact minor amount, currency, original creation time and literal outcome status. Pending and requires_action remain distinct from succeeded, failed and canceled.

The webhook retains each authenticated refund delivery in an append-only inbox, scoped by provider, merchant, live mode and event ID. Exact redelivery returns refund_duplicate without another write; a different payload under that identity returns HTTP 409 and preserves the original. Out-of-order statuses are separate observations, without overwriting a newer outcome. Checkout-only drivers retain their existing behavior.

The immutable snapshot contains no local invoice/allocation authority from provider metadata. Recording it returns refund_recorded, which means delivery capture only. It creates no invoice payment, reservation, subledger posting or financial event. A provider succeeded observation alone does not confirm local cash; the separate local confirmation command requires the original outstanding reservation.

A read-only funding check accepts an explicitly selected local allocation and verifies its original payment, posting and receipt. It retains cash, receivable and paid-base components separately with their captured currency units; later rates and company currency settings do not replace those amounts. Matching a delivery to that basis checks the original provider, merchant, mode, receipt, currency and exact requested amount. This read-only check grants no refundable capacity and performs no reservation or confirmation.

An authorised staff command (not available through the API) can link an already known provider refund ID to that explicit allocation and reserve its original principal. It sends no refund request to the provider and exposes no new API route. Its idempotent source shares remaining principal with operator-recorded refunds and prevents the same allocation from being released into unapplied cash while reserved. An exact authenticated failed or canceled observation releases that reservation once through a separate failure source. A verified success prevents failure release and requires confirmation or reconciliation. Initiation and failure leave payments, cash and subledger rows unchanged; their recorded sources rebuild the same reservation state without emitting financial events. A separate read-only confirmation admission requires a persisted authenticated success for that exact outstanding reservation and its unchanged original funding. Pending, failed, substituted or already released observations are refused. Admission itself creates no confirmation source, payment or posting.

The prospective return calculator keeps the original cash, receivable and paid-base amounts separate. Each partial amount is the difference between cumulative HALF_UP targets; the final return consumes the exact remaining component, including zero-base and large integer amounts. It uses captured units and amounts without reading a current rate or currency catalogue. This pure calculation does not establish prior-return provenance, authorize a confirmation or write cash.

A staff confirmation command records a distinct authenticated-success source and negative provider-owned payment under the original account, settlement, invoice and payment locks. It consumes the reservation, credits provider clearing and restores receivables using separate original cash, receivable and paid-base components. Prior operator and provider returns share the same principal and ordered original-basis prefix; retries of the same confirmation are read-only. Its captured aggregate outcome folds without live lookups or financial event emission. The posting policy retains the same source and original-basis checks in PostgreSQL. Financial rebuild reconstructs failed and confirmed lifecycle outcomes and exact payment, allocation and posting rows from retained sources, without current money facts or new financial events. It consumes an authenticated completed provider refund; it does not submit an external refund request. Legal debit adjustments use the separate explicit correction link described below.

RecordInvoiceDebitAdjustment links an original posted standard invoice to a separately issued positive standard correction for the same current liable account. The caller supplies an idempotency key and a reason. The existing invoices.issue permission and current warehouse access to both documents authorize the command; draft issuance policy stays separate. Both invoices and their contributors are locked in the existing ranked mutation context. Only the original aggregate advances for a new link; an exact retry changes neither aggregate.

InvoiceDebitAdjustmentPosted captures both immutable InvoiceIssued identities, their original posting and conversion facts, the actor, reason and UTC time. invoice_debit_adjustments is its append-only projection. Each correction can belong to one link. The link creates no payment, receivable adjustment, revenue or financial posting: each independently issued invoice already owns its own economic posting. Neither invoice's totals, existing applied credits or original money units are rewritten. Replay uses the captured issue sources, without current rates, currency precision, authority or inferred historical links. Removing admission is refused while evidence remains.

Period-end revaluation

RevalueCurrency admits a revaluation only for an explicitly admitted, open period, an installed monetary ledger account key (receivables, payables, manual_cash_control or provider_clearing), and a foreign currency. Period admission and closure require settings.manage and access to all warehouses. These records govern revaluation admission; they do not close the whole ledger. Missing or closed period records refuse without an event or posting.

The producer captures verified monetary posting balances through period end, preserving their original currency and base minor units. It requires a positive direct closing quote effective on that exact date. Missing quotes, missing original units or incompatible base identities refuse without replacing historical evidence. A nonzero difference creates a dedicated balanced unrealised FX adjustment; zero difference creates no financial posting. The original transactions, rates and postings remain unchanged.

The tenant-aware ReverseDueCurrencyRevaluations scheduled job runs every minute and records an idempotent reversal when the next period's first day is due. It uses the original captured difference and currency identities, even if rates or the configured base currency have changed. No future inverse is booked early, because accounting exports and general cash readers do not automatically filter future posting dates. Delayed or interrupted queue delivery is recovered from the persisted pending revaluation on a later tick.

A later period refuses with revaluation_prior_reversal_pending until every prior revaluation in the same account and currency has its due reversal recorded. This guard also runs when a dedicated event validates its captured exposure. Once the scheduled reversal is recorded, capture includes all monetary postings through the period-end calendar date.

Repeating the same period/account/currency returns its original receipt; a different scope has a separate identity. Replaying the dedicated events verifies the original posting or inverse without creating a second adjustment or scheduling another effect. These actions are separate from report presentation conversion, depreciation and base-amount rebuilds.

Partial money results in aggregates and reports

Invoice and rental base-money measures on GET /api/v1/aggregate/{model}, POST /api/v1/reports/execute, and POST /api/v1/reports/{report}/execute return HTTP 200 with partial results when individual rows fail base-money admission using the existing currency, precision, provenance or conversion-evidence validators. Reports selecting at least one base-money field use the same admission policy. Only money SUM/AVG/MIN/MAX measures exclude these rows. Counts (including counts of money fields), non-money measures and their group populations still include every scoped, filtered row. If any selected money field fails admission, that row is excluded from all selected money measures. No stored amounts, currencies or rates are repaired by a read.

For partial results, the enclosing data.meta for the aggregate or report result contains complete: false, incomplete_reason: "money_rows_excluded", and excluded_money_rows: a list of objects with id, source, code, reason, and message. Reports also include window (current, comparison, or an additional-window name). code preserves the evidence validator's refusal code; reason is foreign_rate_provenance_missing or stored_money_evidence_invalid; message names the affected money fields and explains the exclusion. For example:

{"complete":false,"incomplete_reason":"money_rows_excluded","excluded_money_rows":[{"id":19,"source":"rentals","code":"base_amount_evidence_incomplete","reason":"foreign_rate_provenance_missing","message":"Excluded subtotal from money totals: the foreign exchange rate has no usable recorded provenance.","window":"current"}]}

Report financial metadata preserves the incomplete status; CSV and PDF exports identify each excluded source and row. When there are no exclusions, excluded_money_rows and the money-exclusion status fields are absent (other report completeness metadata may still apply). Consumers must inspect completeness before treating money totals as the full population. Groups containing only excluded money contributors remain present in reports, with their counts/non-money values; empty money sums display zero and empty averages/minima/maxima remain null.

Invoice-header measures exclude failing rows rather than returning 422 invoice_base_evidence_invalid. This partial-result policy is limited to invoice and rental header measures. Rental measures without a captured base column (rental_total, sale_total, service_total, agreed_total, and agreed_price_original_total) use the same per-row exclusion contract, including when selected without a mapped header measure. Their existing unconverted-money evidence checks remain authoritative: foreign category money is excluded even when the header has a valid frozen rate. This policy does not convert those fields or relax statement-time checks. Unconverted invoice-header measures retain their existing refusal contracts. Child aggregates still refuse invalid parent evidence with invoice_parent_base_evidence_invalid, rental_parent_base_evidence_invalid, or purchase_order_parent_base_evidence_invalid; other sources and cross-row/statement-time evidence checks retain their existing 422 refusal contracts. Dashboards, account insights, credit exposure and project rollups report incomplete money; a list column shows Incomplete and an export leaves the base cell empty.

Purchase order documents

Purchase order documents are append-only HTML/CSS snapshots of a sent PO. A document from another purchase order returns 404 under the requested parent. The Finance read API scopes them to their purchase order:

Action Route HTTP
List snapshots GET /api/v1/purchase_orders/{purchaseOrder}/documents (api.v1.purchase_orders.documents.index) 200 JSON
Show one snapshot GET /api/v1/purchase_orders/{purchaseOrder}/documents/{document} (api.v1.purchase_orders.documents.show) 200 JSON
Stream PDF GET /api/v1/purchase_orders/{purchaseOrder}/documents/{document}/pdf (api.v1.purchase_orders.documents.pdf) 200 application/pdf

The PDF route re-renders the stored snapshot through PdfDriverManager and streams bytes. It does not redirect or return 202. Requires purchase_orders.view and the purchase_orders:read token ability, plus view access on the parent purchase order. The UI Documents card on a PO show page is the same projection — see Sub-Hire & Procurement.

Payment custom fields

Payment recording accepts custom_fields keyed by field name. Values are validated against the active payment field definitions before the payment event is recorded; a required or invalid field refuses the command without recording a payment.

String codes

Purchase-order status_code accepts open, authorised, sent, completed or cancelled; state is draft or order. Repair repair_type is repair, lost or safety. Report schedules use lowercase weekday names for day_of_week. Preference items_per_page accepts 10, 25, 50 or 100, with 25 as the schema example.

Integration identities and synchronisation

Draft invoices support external_ref and PUT /api/v1/invoices/by-external-ref/{ref}; an existing invoice must still pass ordinary draft-update rules. Accounts, invoices, credit notes and payments support nested integration-mappings, with reverse lookup by provider and external ID. An issued invoice may receive a mapping without changing its financial contents. See Integration identities.

Both GET /api/v1/payments and GET /api/v1/invoices/{invoice}/payments accept filter[created_at] and filter[updated_at]. Use include_deleted=true or filter[deleted_at] to reconcile retained removals where the model has a deletion marker. Invoice and credit-note line edits advance their parent's updated_at. See sync conventions for cursor examples and timestamp boundaries.

Custom fields and imported credits

Credit-note creation, payment creation and refund commands accept the flat custom_fields object through their invoice endpoints. Credit-note and invoice-payment responses expose optional custom_fields, including nested invoice responses. Payment and credit-note lists support their documented custom-field filters.

Imported credit notes can have status historic, import_source_id and original_issued_at. Historic credits are immutable; use those fields as migration evidence and do not attempt to edit their custom fields. Clients must accept historic in responses and filter[status][eq].

Write-offs, reversals, settlement allocations and write-off approval requests always require a 1–255 character Idempotency-Key. A 425 may contain only message; a write-off-related 409 may contain message and optional errors. See Idempotency.

Posting lock date

finance.posting_lock_date closes dates inclusively for imported payment and refund backdating. It is nullable, must be before today, and is managed through Finance settings by settings.manage. Dates use UTC. Closed revaluation periods and recorded foreign-currency revaluations also constrain backdating. Today-dated postings are unaffected. Moving the lock backwards reopens the period, with the normal settings audit trail.