Skip to main content

Update Vendor Deposit

PUT 
/api/vendor-deposits/:vendorDepositId

Update a vendor deposit. All fields are optional (sometimes).

Required scope: accounting:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Editability by status: draft and pending-approval deposits accept the full field set. Approved/paid/applied deposits accept only the descriptive fields — deposit_date, due_date, external_reference, vendor_invoice_number, vendor_invoice_date, notes — plus the two apply-behaviour settings proportional_apply_enabled and auto_apply_enabled; sending any other field returns 422 with the locked field(s) named. Terminal deposits (cancelled, void, refunded, written off) cannot be updated at all.

Bank details: payee_bank_details may be updated on draft/pending deposits. Changing the snapshot without bank_details_verified: true clears the verification stamps — the deposit must then be re-verified before submit-for-approval succeeds. Details matching the supplier profile collapse to null.

Supplier deposit invoice: vendor_invoice_number and vendor_invoice_date record the supplier's invoice for this deposit or stage payment — the deposit is that invoice's record (a down-payment invoice). Do not create a goods invoice for a deposit. vendor_invoice_date must have a year between 1990 and 2100 (422 otherwise). Both fields remain editable after approval.

Apply behaviour: auto_apply_enabled (boolean, nullable) overrides whether this deposit auto-applies when a new bill is raised against its purchase order; null falls back to the supplier setting and then the tenant-wide accounting setting, and the resolved value is returned as auto_apply_effective. proportional_apply_enabled (boolean, nullable) caps each automatic application at (bill total ÷ purchase order total) × deposit amount, so a bill covering one shipment of a staged order does not consume the whole deposit. null inherits — the supplier's proportional_apply_deposits when set, else on when the purchase order's payment term has a payment schedule (a staged term), else the account setting vendor_deposits_proportional_apply_enabled — and the resolved value is returned as proportional_apply_effective with proportional_apply_source (deposit, supplier, term, global) naming the step that decided it. Both settings remain editable after approval because they govern how the remaining balance is applied to future bills.

Accepts related_purchase_order_id (integer, nullable) — third-party PO reference, mutually exclusive with purchase_order_id; must belong to a different supplier than the deposit. Validation runs against the effective post-update state (absent fields fall back to the deposit's current values).

Payee bank details: while a deposit is Draft or Pending Approval you can change payee_bank_details (string, max 2000) and set bank_details_verified: true to confirm you checked the new details with the supplier out of band. Sending bank_details_verified: true on its own verifies the deposit's current bank details. A deposit whose changed bank details aren't verified can't be submitted for approval or approved. After approval, bank details are locked.

Request​

Responses​

OK

Response Headers
    Content-Type