PATCH/businesses/{bid}/documents/{id}

Update a draft

PATCH /businesses/{bid}/documents/{id}

Requires the documents scope.

Drafts only. An issued document answers 409 not_draft; it is immutable at the database engine.

Send only what changes. lines, payments and settles are each replaced whole when present. The customer changes by partyId (an inline party object is read on create only). docType and priceMode are fixed when the draft is created and are ignored here: to change either, delete the draft and create it again. A create replayed with the same Idempotency-Key returns the existing draft unchanged, so an edited order is a PATCH, or a delete and a new create.

Path parameters

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

Body

Field	Type		Description
`docType`	integer	required	300 (proforma, חשבונית עסקה: a demand for payment, numbered and immutable but not a tax document and never income) / 305 / 320 / 400. A 330 is created only through the credit-note endpoint. One of: `300`, `305`, `320`, `400`.
`party`	object		`{partyId}` to reference a saved party, or an inline `{name, taxId?, phone?, email?, address?}`. Omit entirely for an anonymous cash receipt.
`party.partyId`	string
`party.name`	string
`party.taxId`	string
`party.phone`	string
`party.email`	string
`party.address`	string
`priceMode`	string		`net` (the default: line prices are ex-VAT) or `gross` (line prices include VAT; the total anchors to the gross sum and VAT is derived). Gross is what a consumer-facing price list wants. One of: `net`, `gross`. Default `net`.
`lines`	array of DocumentLine		Required for 305/320.
`payments`	array of Payment		Required for 320/400.
`note`	string		≤500 chars.
`documentDate`	string		Defaults to today, Asia/Jerusalem.
`valueDate`	string		Defaults to today.
`discountAmount`	integer		Document-level discount. Integer agorot (₪1 = 100).
`withholdingAmount`	integer		ניכוי במקור. Integer agorot (₪1 = 100).
`currency`	string		Denominate the document in a foreign currency. Then every amount in this body (lines, discounts, payments) is in that currency's minor unit (cents, not agorot) and the ledger converts to shekels at issue. One of: `ILS`, `USD`, `EUR`, `GBP`, `CHF`, `AUD`, `CAD`. Default `ILS`.
`fxRate`	number		ILS per 1 unit of `currency`: your own rate (the bank's conversion, a contract rate). Omit to use the Bank of Israel שער יציג of the document date, fetched at issue; if none can be had the issue answers `fx_rate_required`.
`fxRateDate`	string		The day your `fxRate` is from, printed beside it.
`zeroVat`	boolean		State מע"מ בשיעור אפס (סעיף 30(א) לחוק מע"מ: a service to a foreign resident, export). Lines carry 0% VAT and the document prints the legal basis. Your claim; BillOS does not check the conditions. Ignored on a receipt or for a עוסק פטור.
`lang`	string		Print the document in English (`en`): an LTR page, English labels, dates as `September 4, 2026`, the email that carries it in English too. The legal marks (מסמך ממוחשב, מקור/העתק, the signature line) stay in Hebrew beside their English. Line descriptions and notes print as you send them. One of: `he`, `en`. Default `he`.
`brandingThemeId`	string		The branding theme it prints in (GET /businesses/{bid}/branding-themes). Omit or `null` for the customer's default, else the main design; `"main"` for the main design whatever the customer's default. Frozen at issue: the issued row names the theme it used, `null` for the main design.
`allocationNumber`	string		מספר הקצאה, when you already hold one.
`dueDate`	string		The payment term (לתשלום עד) to print on a 305/300; ages the receivable.
`settles`	array of object		On a receipt (400): the issued invoices (305) or proformas (300) this receipt pays, each with an optional agorot amount; without one the receipt covers as much of the balance as it can, in order. Checked at issue against the balances of that moment. Printed on the receipt as "על חשבון". Same customer only.
`externalRef`	string		Idempotency key, interchangeable with the `Idempotency-Key` header.

Response

200: { "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.

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 PATCH "$BASE/businesses/$BID/documents/$DOC_ID" \ -H "X-Api-Key: $KEY" \ -H "Content-Type: application/json" \ -d '{ "docType": 320, "party": { "name": "דנה לוי", "taxId": "514667426", "phone": "0521111111", "email": "dana@example.com", "address": "הרצל 12, תל אביב" }, "priceMode": "gross", "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "payments": [ { "method": 3, "amount": 120000 } ], "externalRef": "order-8812" }'

const res = await fetch(`${BASE}/businesses/${BID}/documents/${DOC_ID}`, { method: 'PATCH', headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "docType": 320, "party": { "name": "דנה לוי", "taxId": "514667426", "phone": "0521111111", "email": "dana@example.com", "address": "הרצל 12, תל אביב" }, "priceMode": "gross", "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "payments": [ { "method": 3, "amount": 120000 } ], "externalRef": "order-8812" }), }) const data = await res.json() if (!data.ok) throw new Error(data.reason)

import requests res = requests.patch( f"{BASE}/businesses/{BID}/documents/{DOC_ID}", headers={"X-Api-Key": KEY}, json={ "docType": 320, "party": { "name": "דנה לוי", "taxId": "514667426", "phone": "0521111111", "email": "dana@example.com", "address": "הרצל 12, תל אביב" }, "priceMode": "gross", "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "payments": [ { "method": 3, "amount": 120000 } ], "externalRef": "order-8812" }, ) data = res.json()