POST/businesses/{bid}/documents/{id}/credit-note

Correct with a credit note, in full or in part

POST /businesses/{bid}/documents/{id}/credit-note

Requires the documents scope.

The only way to undo an issued 305 or 320: issues a linked חשבונית מס זיכוי (330). With no body it mirrors the original in full and the source is marked cancelled. With lines or amount it credits PART of it (הוראה 23א: a transaction cancelled "כולה או מקצתה" or an amount that changed): the source stays open on the remainder, reason is required, and the sum of all credits against a document may never exceed its total. For a receipt (400) it issues a negative receipt (amount for a partial refund). The credit prints "בגין חשבונית מס 1234 (date)" and the reason. Nothing is ever deleted (הוראה 23).

Send an Idempotency-Key (your refund id): a credit note is as permanent as the document it corrects, and a retry with the same key answers the credit note already issued with deduped: true instead of a second one. A key that already produced a different document is 409 conflict.

Path parameters

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

Headers

Name	Type		Description
`Idempotency-Key`	string		Your own stable id for this call. A retry returns the same row with `deduped: true` instead of creating a duplicate. Interchangeable with `externalRef` in the body.

Body (optional)

Field	Type		Description
`reason`	string		Printed on the credit note. Required for a partial credit.
`amount`	integer		Partial credit: the amount to credit, VAT INCLUDED, in the document's minor unit (agorot, or cents on a foreign-currency document). One line "זיכוי חלקי בגין …" is written for it. On a receipt: the part refunded.
`lines`	array of DocumentLine		Partial credit line by line: the credited items with their quantities and prices (ex-VAT unless `priceMode: gross`). Not on a receipt.
`priceMode`	string		How `lines` prices are stated. One of: `net`, `gross`. Default `net`.
`refund`	boolean	object		On a 320 (חשבונית מס-קבלה): also issue the negative receipt that records the money given back, for the credit's total. `true`, or `{ method }` (a payment-method code or alias).
`externalRef`	string		The idempotency key in the body, interchangeable with the `Idempotency-Key` header.

Response

201: { "ok": true, … }

Field	Type		Description
`ok`	boolean	required
`document`	Document	required	A draft is freely mutable. An issued document is immutable forever, blocked at the database engine, not merely in application code.
`source`	object
`source.id`	string
`source.cancelledById`	string		Set when the credits now add up to the total.
`source.creditedAmount`	integer		Credited against the source so far, this one included. Integer agorot (₪1 = 100).
`source.remaining`	integer		Still creditable. Integer agorot (₪1 = 100).
`refund`	Document		A draft is freely mutable. An issued document is immutable forever, blocked at the database engine, not merely in application code.
`deduped`	boolean		true when this `Idempotency-Key` had already issued this credit note and the call changed nothing.
`warnings`	array of string		As on issue.

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).

curl -X POST "$BASE/businesses/$BID/documents/$DOC_ID/credit-note" \ -H "X-Api-Key: $KEY" \ -H "Content-Type: application/json" \ -d '{ "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "priceMode": "gross", "externalRef": "order-8812" }'

const res = await fetch(`${BASE}/businesses/${BID}/documents/${DOC_ID}/credit-note`, { method: 'POST', headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "priceMode": "gross", "externalRef": "order-8812" }), }) const data = await res.json() if (!data.ok) throw new Error(data.reason)

import requests res = requests.post( f"{BASE}/businesses/{BID}/documents/{DOC_ID}/credit-note", headers={"X-Api-Key": KEY}, json={ "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "priceMode": "gross", "externalRef": "order-8812" }, ) data = res.json()