Settlements
List a counterparty’s settlements
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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
Credential: a company's API key or OAuth token.
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.
Undo a settlement
Credential: a company's API key or OAuth token.
Reverses a settlement: every entry it linked is open again for the amount it applied, and every
journal entry it posted — its difference, a VAT reclass, a receivable transfer — gets a linked
reversal dated today. The settlement stays on the trail, marked reversed.
Undoing an undone settlement changes nothing and answers with the earlier outcome, so a retry after a timeout is safe.
Refused with 400 while today’s accounting period is closed, and while a later settlement still draws on an advance this one created — undo that one first.
Required Scope
journal-entries-write
path Parameters
settlementIdID of the settlement (UUID)
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Undo a settlement › Request Body
reasonWhy the settlement is being undone. Stored on the settlement and shown in the activity feed of every entry it linked.
Undo a settlement › Responses
The settlement was undone
idThe settlement that was undone.
differenceReversalJournalEntryIdThe reversal of the settlement’s difference entry, or null when it posted none.
vatReclassReversalJournalEntryIdThe reversal of the settlement’s VAT reclass entry, or null when it posted none.
receivableTransferReversalJournalEntryIdThe reversal of the settlement’s receivable transfer, or null when it posted none.
Check what undoing a settlement would do
Credential: a company's API key or OAuth token.
Reports the entries the settlement linked, which are open again once it is undone, and the journal entries it posted, which each get a linked reversal. Nothing is changed.
The reversal posts today, so today’s accounting period has to be open: a closed one answers 400
with the same code the reversal itself would. A settlement already undone answers
alreadyReversed: true; undoing it again changes nothing.
Required Scope
journal-entries-write
path Parameters
settlementIdID of the settlement (UUID)
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Check what undoing a settlement would do › Responses
What the reversal would do. Nothing was changed.
settlementIdThe settlement this preview is about.
alreadyReversedTrue when the settlement was already undone. Reversing it again changes nothing and answers with the earlier outcome.
reversalDateThe date the mirror entries post on: today. Its accounting period has to be open.
The entries the settlement linked. Each is open again for what the settlement applied to it.
journalEntriesMirroredJournal entries the settlement posted (its difference, VAT reclass and receivable transfer) that the reversal mirrors with a linked reversal entry. Empty when the settlement posted nothing.
Check what settling these entries would do
Credential: a company's API key or OAuth token.
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.