POST/businesses/{bid}/documents/{id}/settlements

Match an issued receipt to an invoice

POST /businesses/{bid}/documents/{id}/settlements

Requires the documents scope.

For money received "on account" and matched afterwards: allocates part of an ISSUED receipt's unallocated amount to an open invoice or proforma of the same customer. Not printed on the receipt (that paper is done); removable. A receipt created with settles needs none of this. Fires document.paid when the invoice reaches zero.

Path parameters

Name	Type		Description
`bid`	string	required	Business id, from `POST /businesses`.
`id`	string	required	Receipt id.

Body

Field	Type		Description
`documentId`	string	required	The invoice or proforma.
`amount`	integer		Optional: defaults to what is left on the receipt, capped at the balance. Integer agorot (₪1 = 100).

Response

201: { "ok": true, … }

Field	Type		Description
`ok`	boolean	required
`settlement`	SettlementRow	required	One receipt paying (part of) one invoice or proforma.
`target`	Settlement		The open-items view of an issued invoice (305) or proforma (300): total minus the receipts allocated to it minus the credit notes based on it.
`paid`	boolean		The target reached a zero balance with this allocation.

Errors: 400, 401, 403, 404, 409, 429. Every failure answers { "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }: branch on reason, and read hint for what to change (https://docs.billos.co.il/errors.md).

const res = await fetch(`${BASE}/businesses/${BID}/documents/${DOC_ID}/settlements`, { method: 'POST', headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "documentId": "string" }), }) const data = await res.json() if (!data.ok) throw new Error(data.reason)