Skip to main content

Create Vendor Deposit

POST 
/api/vendor-deposits

Create a new vendor deposit. Returns 201 with the created deposit.

Required scope: accounting:write

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

Proforma invoice / payment request fields:

  • payee_bank_details (string, nullable, max 2000) — payee bank block captured from the supplier's proforma invoice. If it matches the supplier profile's wire_instructions (case/whitespace-insensitive) it is normalized to null ("per supplier profile").
  • bank_details_verified (boolean, default false) — acknowledgment that details differing from the supplier profile were verified out-of-band. When true (and a differing snapshot is present), bank_details_verified_at/bank_details_verified_by are stamped. A deposit with an UNVERIFIED differing snapshot saves as draft but cannot be submitted for approval (422).

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.

Optional related_purchase_order_id (integer) records a third-party purchase order reference: a PO owned by a DIFFERENT supplier that this deposit economically belongs to (e.g. DDP freight prepaid to a forwarder against the goods supplier's PO). It is mutually exclusive with purchase_order_id, must not belong to the deposit's own supplier, and never affects the referenced PO's expected-deposit milestones or deposit capacity. purchase_order_id must belong to the deposit's own supplier.

Proportional application: proportional_apply_enabled (boolean, nullable) caps each automatic application of the deposit at (bill total ÷ purchase order total) × deposit amount, so a bill covering one shipment of a staged order absorbs only its share. null (or omitting the field) inherits: the supplier's proportional_apply_deposits when that is 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. true / false override that chain for this deposit. Responses return the resolved value as proportional_apply_effective and name the deciding step in proportional_apply_source (deposit, supplier, term or global).

Approval policy: While the purchase-order approval policy is enabled, a deposit cannot be linked to a purchase order that is not yet approved or whose changes await re-approval (422 approval_required / approval_pending).

Request​

Responses​

Created

Response Headers
    Content-Type