Update a document

Updates an existing document with partial data. IMPORTANT: Only DRAFT documents can be updated. Issued or canceled documents are immutable to maintain audit trail and tax compliance.

Updatable Fields (DRAFT documents only):

Client: clientId (changes which client receives the document)
Dates: issueDate, dueDate
Currency and FX: currency, fxRate
VAT mode: vatMode (exclusive, inclusive, none)
Line items: Complete replacement of items array
Notes: Internal notes, payment terms
Original document reference (for credit notes)

Status Workflow:

DRAFT → DRAFT: Allowed - update any field
ISSUED → any: FORBIDDEN - issued documents are immutable
CANCELED → any: FORBIDDEN - canceled documents are immutable

Why Immutability?: Israeli tax law requires that issued invoices cannot be modified after issuance. Any corrections must be made via credit notes that reference the original document.

Recalculations: All totals (subtotals, VAT, grand total) are automatically recalculated when line items change.

Multi-Tenant Security: Only users who own the business that created this document can update it.

Example Use Cases:

Edit draft invoice before sending to client
Add/remove line items before finalization
Change client if document was created for wrong recipient
Update payment terms or due date
Correct pricing errors before issuance

To Correct Issued Documents: Create a credit note (docType: CREDIT_NOTE) that references the original document via originalDocId field.

Authorization

X-Api-Key<token>

Business API key, e.g. vuz_ab12cdef... Created via Settings → Integrations → API Keys. Unlike partner keys, a public API key's STRING does not encode its environment — isolation instead comes from a completely separate sandbox database: a key minted on the Sandbox server (above) only ever reads/writes sandbox data and can never see or affect production, regardless of what the key looks like.

In: header

Path Parameters

id*string

Document unique identifier (UUID)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

businessId?string

Business ID (multi-tenant scoping). Document belongs to this business.

Formatuuid

brandId?|

Brand (שם מסחרי) id this document is issued under. Drives the document identity + design (name/logo/colors/template) at finalization — never the document number (numbering stays business-scoped → one continuous series across brands). Omit to use the business default brand.

Formatuuid

clientId?|

Client ID (UUID). Optional - can provide clientName instead for auto-creation.

Client Lookup Flow:

If clientId is provided → use existing client
If only clientName is provided → create new client with that name
At least one of clientId or clientName must be provided

Formatuuid

supplierId?|

Supplier ID (UUID) for PURCHASE-side documents (W3.2 — e.g. PURCHASE_ORDER). When set, the document is addressed to this supplier instead of a client; the supplier name is snapshotted and a PO lifecycle status (poStatus) is initialized. Leave unset for all sales documents.

Formatuuid

clientName?|

Client name for auto-creation. If provided without clientId, a new client will be created.

Auto-Creation Behavior:

Creates new client with type=PRIVATE by default
Client will be linked to the specified businessId
Useful for quick document creation without pre-creating clients

Lengthlength <= 100

client?

Full inline client details for auto-creation (public-API convenience).

Client Lookup Flow (extended):

If clientId is provided → use existing client (client/clientName ignored)
Else if client is provided → create a new client with these details (name, type, email, phone, vatNumber, address)
Else if only clientName is provided → create new client with just that name (legacy behavior, unchanged)
At least one of clientId, clientName, or client.name must be provided

branchId?|

Client branch ID (UUID). Optional - when provided, the branch address and VAT number will override the client's default values on the document. Used for franchise clients with multiple locations.

Formatuuid

clientDisplayName?|

Custom display name for client (overrides clientName on documents). Useful when client wants a different name on the invoice.

Lengthlength <= 500

docType?string

Document type determines tax treatment, numbering, and validation rules.

Value in

"order"
"delivery_note"
"agent_delivery_note"
"return_note"
"tax_invoice"
"consolidated_invoice"
"tax_invoice_receipt"
"credit_note"
"reservation_invoice"
"agent_invoice"
"receipt"
"donation_receipt"
"cash_withdrawal"
"bank_deposit"
"purchase_order"
"purchase_delivery_note"
"purchase_return"
"purchase_tax_invoice"
"purchase_credit_note"
"opening_balance"
"inventory_in"
"inventory_out"
"warehouse_transfer"
"inventory_adjustment"
"production_in"
"production_out"
"quote"
"deal_bill"
"work_order"

issueDate?string

Issue date (YYYY-MM-DD, תאריך הנפקה — placeholder at draft stage). Two-date model (dev_features/2026-07-05-document-date-two-field-model): at FINALIZE time this is ALWAYS forced to today (Israel calendar day) regardless of what is stored here — never user-editable at that point. While the document remains a DRAFT this value is a placeholder only; the real, user-facing fiscal date is documentDate below (defaults to this value when omitted).

Formatdate

documentDate?|

Fiscal date (YYYY-MM-DD, תאריך המסמך) — the date the customer/PDF/lists see, and the date fiscal-period logic (VAT reports, ledger) anchors to. Two-date model (dev_features/2026-07-05- document-date-two-field-model). Defaults to issueDate when omitted. Validated against issueDate (documentDate <= issueDate, >= issueDate - 60 days, same calendar/tax year) — see validateDocumentDate (documents/utils/sequenced-doc-types.util.ts). Re-validated (and, if backdated, gated behind an accountant-acknowledgment flag) at finalize — see FinalizeDocumentDto.documentDate/backdateAck.

Formatdate

backdateAck?boolean

Accountant-acknowledgment flag (two-date model, dev_features/2026-07-05-document-date- two-field-model). Required (must be true) whenever the resolved documentDate is TIER 2 — strictly earlier than the last ISSUED document of the same type (see validateDocumentDate in documents/utils/sequenced-doc-types.util.ts). Threaded through create()/update() so saving/editing a DRAFT with a Tier-2 documentDate does not throw before the user has had a chance to tick the accountant-consultation checkbox in the UI — the SAME flag is re-supplied (and re-validated) at finalize (FinalizeDocumentDto.backdateAck), where it is actually persisted to the audit columns (backdateAckAt/backdateAckByUserId). A draft save/update never stamps those columns itself — only finalize does, since only an ISSUED document's backdating is a fact worth auditing.

Defaultfalse

dueDate?|

Due date for payment (YYYY-MM-DD). If provided, this explicit caller value always wins. If omitted, the server computes it from the resolved payment terms (paymentTermsId, or the client's effective terms, or the business default — every business gets a default term after Workstream D's seeding) via PaymentTerms.calculateDueDate(documentDate) — the fiscal anchor, not issueDate (two-date model Decision #5). Falls back to +30 days only when no payment terms could be resolved at all.

Formatdate

paymentTermsId?|

Payment terms ID (UUID, references payment_terms). Optional.

Resolution Flow:

If provided → used directly (must belong to this business).
If omitted → resolved automatically: the client's effective payment terms (client override via client_settings.paymentTermsId, else the business default isDefault=true term) via ClientSettingsService.getEffectivePaymentTerms.
The resolved term's name is snapshotted onto the document (paymentTermsText) and used to compute dueDate (unless dueDate was explicitly provided above).

Formatuuid

currency?string

Currency code (ISO 4217). Defaults to business default currency.

Default"ILS"

Value in

"ILS"
"USD"
"EUR"

fxRate?|

Foreign exchange rate (if currency is not base currency). Used for reporting.

Range0.0001 <= value

vatMode?string

VAT mode: exclusive (VAT added), inclusive (VAT included), or none (no VAT)

Default"exclusive"

Value in

"exclusive"
"inclusive"
"none"
"zero_rated"

vatRate?|

Custom VAT rate for this document as percentage (e.g., 18 for 18%, 17 for 17%). If not provided, the rate is calculated based on client type:

OSEK_PATUR / FOREIGN clients: 0%
All other clients: Current legal rate (18%)

Range0 <= value <= 100

items?array<>

Line items for this document. Required for all documents except invoice-linked receipts (items will be auto-copied from invoice).

Items1 <= items

notes?|

Additional notes (Hebrew or English, rich HTML). Visible on printed document.

Lengthlength <= 10000

originalDocumentId?|

Reference to original document ID (required for credit notes)

Formatuuid

parentDocumentId?|

Reference to parent document ID (for invoice-linked receipts)

Formatuuid

origin?string

Origin of document creation (web, api, whatsapp, mobile, import, system). Defaults to "web".

Default"web"

Value in

"web"
"api"
"whatsapp"
"telegram"
"mobile"
"import"
"system"
"woocommerce"
"mcp"

payments?array<>

Payment entries for receipts. Each payment can have different payment methods and amounts.

documentDiscountType?string

Document-level discount type: PERCENT or FIXED.

PERCENT: documentDiscountPercent field is used (0-100)
FIXED: documentDiscountAmount field is used as exact discount value

Default: No document discount

Value in

"PERCENT"
"FIXED"

documentDiscountPercent?number

Document-level discount percentage (0-100). Used when documentDiscountType = PERCENT.

Formula: documentDiscountAmount = itemsTotal × (documentDiscountPercent / 100)

Range0 <= value <= 100

Default0

documentDiscountAmount?number

Document-level discount amount (fixed value). Used when documentDiscountType = FIXED. This is the calculated discount amount that will be subtracted from the items total.

Range0 <= value

subTotal?number

REQUIRED when items provided: Document subtotal before VAT (calculated by frontend). Server validates this equals sum of all lineSubTotal values (±0.01).

Formula: subTotal = Σ(items.lineSubTotal)

vatTotal?number

REQUIRED when items provided: Document VAT total (calculated by frontend). Server validates this equals sum of all lineVatTotal values (±0.01).

Formula: vatTotal = Σ(items.lineVatTotal)

grandTotal?number

REQUIRED when items provided: Document grand total including VAT and after document discount (calculated by frontend). Server validates this equals: Σ(items.lineGrandTotal) - documentDiscountAmount (±0.01).

Formula: grandTotal = Σ(items.lineGrandTotal) - documentDiscountAmount

partnerExternalRef?|

Partner's internal order/document ID — set when this document was issued via the Partner API (apps/client-api/src/partner-api/). Unique within the merchant business. Not used by the client-dashboard create form.

metadata?|

Internal passthrough metadata, stored verbatim on the document. Used e.g. by PaymentCheckoutService.issueDocumentForPayment to carry the merged page+sale merchant metadata (webhooks-automation plan §1.9-C) — not surfaced on the client-dashboard create form.

clearDueDate?boolean

Explicitly clear the document due date (תאריך פירעון) — sets it to NULL. Omitting dueDate leaves the existing value untouched; this flag is the only way to null it. An explicit non-blank dueDate in the SAME request always wins over this flag.

Response Body

`application/json`

curl -X PATCH "https://example.com/documents/880e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "880e8400-e29b-41d4-a716-446655440000",  "createdAt": "2025-11-09T09:31:07.507Z",  "updatedAt": "2025-11-09T09:31:07.523Z",  "deletedAt": null,  "docType": "quote",  "docNumber": null,  "status": "draft",  "issueDate": "2025-11-09",  "issueTime": "14:32:07",  "documentDate": "2025-11-05",  "dueDate": "2025-12-09",  "documentDatePeriodClosed": true,  "backdateAckAt": "2019-08-24T14:15:22Z",  "backdateAckByUserId": "7009be0c-f167-48ba-92d0-be39eb8a403b",  "paymentTermsId": "990e8400-e29b-41d4-a716-446655440000",  "paymentTermsText": "שוטף + 30",  "currency": "ILS",  "fxRate": null,  "vatMode": "exclusive",  "vatRateDefault": 17,  "subTotal": "150.00",  "vatTotal": "25.50",  "grandTotal": "175.50",  "clientName": null,  "clientTaxId": null,  "clientAddress": null,  "notes": null,  "metadata": null,  "originalDocumentId": null,  "parentDocumentId": null,  "cancelledByDocumentId": null,  "pdfPath": null,  "publicSlug": "j3AxtCjwHS",  "isPublicEnabled": true,  "clientPhoneSnapshot": "+972522456789",  "branchId": "string",  "branchName": "string",  "parentClientName": "string",  "signedAt": null,  "signatureImagePath": null,  "signatureName": null,  "signatureNote": null,  "outstandingAmount": null,  "paidAt": null,  "paymentStatus": "UNPAID",  "documentBalance": 1000,  "totalPaymentsReceived": 0,  "totalCreditsApplied": 0,  "roundingAdjustment": -0.01,  "paymentStatusUpdatedAt": null,  "paymentLinkUrl": "https://pay.vuz.co.il/abc123def456",  "paymentLinkId": "990e8400-e29b-41d4-a716-446655440000",  "paymentLinkStatus": "active",  "paymentLinkExpiresAt": "2025-12-25T00:00:00.000Z",  "isClosed": false,  "closedAt": null,  "closedBy": null,  "isInteractive": false,  "interactiveStatus": "negotiation",  "publicToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",  "publicTokenExpiresAt": "2025-12-25T00:00:00.000Z",  "negotiationVersion": 1,  "business": {    "id": "50596d36-8006-4aeb-a29e-ca78edddb2df",    "businessName": "אקו דב",    "ownerPhone": "972527253023",    "vatRate": 18,    "currency": "ILS",    "vatNumber": "300160629",    "logoPath": null,    "address": null,    "email": "naor@echo-dev.co.il",    "businessMeta": {      "logoUrl": "/uploads/logos/fd32d6f3-f790-4999-b30a-df360993123b.jpg"    },    "userId": "45b9de13-426f-45f8-98f8-a8a8961acf34",    "isActive": true,    "isOnTrial": true,    "trialEndDate": "2025-11-11"  },  "businessId": "50596d36-8006-4aeb-a29e-ca78edddb2df",  "client": {    "id": "3c3e3b30-924b-4a9f-9fbc-516010d36427",    "name": "אקסיומה",    "type": "company_ltd",    "email": "yosi@exioma.co.il",    "phone": "0522456789",    "address": "צנחנים 1 רעננה",    "vatNumber": "111111111",    "contactPerson": "יוסי בוכניק",    "notes": "",    "isActive": true,    "userId": "45b9de13-426f-45f8-98f8-a8a8961acf34",    "businessId": "50596d36-8006-4aeb-a29e-ca78edddb2df"  },  "clientId": "3c3e3b30-924b-4a9f-9fbc-516010d36427",  "createdBy": null,  "updatedBy": null,  "origin": "web",  "originName": "vuz",  "items": [    {      "id": "990e8400-e29b-41d4-a716-446655440000",      "lineNo": 1,      "description": "ייעוץ עסקי - 10 שעות",      "quantity": "10.000",      "unit": "שעות",      "unitPrice": "150.00",      "discountPercent": "0.00",      "vatApplicable": true,      "vatRate": 17,      "lineSubTotal": "150.00",      "lineVatTotal": "25.50",      "lineGrandTotal": "175.50",      "createdAt": "2025-11-09T09:31:07.518Z",      "updatedAt": "2025-11-09T09:31:07.518Z",      "deletedAt": null,      "documentId": "25cd5cfb-8e24-4dd6-b564-0b3c06cb9056"    }  ],  "payments": [    {      "id": "990e8400-e29b-41d4-a716-446655440000",      "paymentMethod": "cash",      "paymentProvider": "string",      "amount": 500,      "paymentDate": "2025-11-09",      "notes": "Payment for invoice #123",      "referenceNumber": "REF-12345",      "bankNumber": "12",      "branchNumber": "456",      "accountNumber": "123456789",      "checkNumber": "123456",      "dueDate": "2025-02-15",      "creditCompanyCode": 2,      "cardName": "Visa",      "cardLastDigits": "1234",      "creditTransactionType": 1,      "numberOfInstallments": 3,      "tranzilaTransactionId": "6982",      "tranzilaAuthCode": "0672865"    }  ],  "aiSummaryData": {}}

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`