Settlements
List a counterparty’s settlements
Every settlement recorded against one counterparty, newest first. Name exactly one of customerId or
supplierId.
Reversed settlements are included rather than hidden, because they are part of the trail. Check
reversed before treating one as still standing: a reversed settlement contributes nothing, and the
entries it linked are open again and back on the open-entries listing.
Required Scope
journal-entries-read
query Parameters
customerIdRead the customer’s entries. Mutually exclusive with supplierId; exactly one is required.
supplierIdRead the supplier’s entries. Mutually exclusive with customerId; exactly one is required.
List a counterparty’s settlements › Responses
Settlements recorded against the counterparty
baseCurrencyThe company’s base currency (3-letter ISO).
Settle open entries against each other
Links entries that cancel each other out — a payment against the invoices it pays, a credit note against the invoice it credits — and closes them. Each entry stops appearing as open for the amount applied to it, and whatever is left of a partly-applied one stays open.
Preview it first. The preview takes this exact body and reports the leftover, the postings and any blockers, so there is no reason to discover a refusal by attempting the settlement.
Amounts are magnitudes. amountToApply is always positive and at most the entry’s
remainingAmount; which side of the settlement an entry lands on follows from what it is.
Echo each entry’s version. It refuses the settlement if the entry was edited or reversed
between reading the list and settling, rather than applying against a document that has since
changed.
Paying more than is owed is refused rather than posted — apply the amount that is actually owed and leave the rest of the payment open for the next invoice.
Required Scope
journal-entries-write
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Settle open entries against each other › Request Body
postingDateAccounting date to post the settlement on (YYYY-MM-DD).
The entries to settle against each other — at least two, since a settlement links something owed to something that pays it. All must belong to the named counterparty.
customerIdRead the customer’s entries. Mutually exclusive with supplierId; exactly one is required.
supplierIdRead the supplier’s entries. Mutually exclusive with customerId; exactly one is required.
idempotencyKeyYour own key for this settlement. Sending the same key with the same body returns the original settlement instead of posting a second one, so a retry after a timeout is safe.
Settle open entries against each other › Responses
The settlement was recorded
idThe settlement. Read it back at GET /v1/settlements/{id}.
differenceJournalEntryIdThe journal entry carrying the difference, when the entries did not net to zero. Null when they balanced exactly.
vatReclassJournalEntryIdThe journal entry that moved a prepayment’s VAT onto the invoice it was applied to. Null unless the settlement did that.
Get a settlement
One settlement in full: the entries it linked, how much of each it applied, and the difference posting when they did not net to zero.
An entry’s appliedAmount can be smaller than its originalAmount. A payment is consumed across as
many settlements as it takes, and whatever is left stays on the open-entries listing.
Required Scope
journal-entries-read
path Parameters
settlementIdID of the settlement (UUID)
Get a settlement › Responses
The settlement
idID of the settlement.
postingDateAccounting date the settlement posted on (YYYY-MM-DD).
createdAtWhen the settlement was recorded.
counterpartyTypecounterpartyIdThe customer or supplier the entries belong to.
reversedWhether the settlement has been reversed. A reversed settlement contributes nothing — its entries are open again.
baseCurrencyThe company’s base currency (3-letter ISO).
The entries this settlement linked, and how much of each it applied.
reversedAtWhen it was reversed. Null while it stands.
reversalReasonWhy it was reversed. Null while it stands.
differenceThe difference posting, when the entries did not net to zero. Null when they balanced exactly.
Check what settling these entries would do
Runs the settlement without posting it: what each entry would have applied, what it becomes, what the leftover is and where it would go.
Takes the same body as the settle call, so preview and settle are the identical payload — nothing has to be rebuilt between them, and nothing can differ between what you were shown and what posts.
blockers is the field to read before settling: it carries the codes that would refuse the
settlement, and an empty list is what says the settle call will go through. warnings are worth
checking but do not stop it — a wide rateGap means the entries were booked at rates far enough
apart that the leftover is probably a mis-booked rate rather than a real exchange difference.
Required Scope
journal-entries-write
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Check what settling these entries would do › Request Body
postingDateAccounting date to post the settlement on (YYYY-MM-DD).
The entries to settle against each other — at least two, since a settlement links something owed to something that pays it. All must belong to the named counterparty.
customerIdRead the customer’s entries. Mutually exclusive with supplierId; exactly one is required.
supplierIdRead the supplier’s entries. Mutually exclusive with customerId; exactly one is required.
idempotencyKeyYour own key for this settlement. Sending the same key with the same body returns the original settlement instead of posting a second one, so a retry after a timeout is safe.
Check what settling these entries would do › Responses
What the settlement would do. Nothing was posted.
baseCurrencyThe company’s base currency (3-letter ISO).
postingDateAccounting date the settlement would post on.
What each named entry would have applied to it, and what it becomes.
The lines that would post. Empty when the entries balance and nothing needs a posting.
blockersError codes that would refuse the settlement. A non-empty list means the commit fails with the first of them.
warningsCodes for things worth checking. The settlement would still post.
Which currencies’ entries disagree about the rate, widest first. Present only alongside the rate-gap warning, and null otherwise — it names the rates to check the booked ones against.