Upsert an invoice

Create or update a single invoice. This is one endpoint for both: omit id to create a new invoice (Distru assigns the ID and the human-readable invoice number), or pass an existing invoice's id to update it. Same URL, same request shape.

Every invoice bills an existing sales order, so order_id is required and each line item must reference an order item that belongs to that order. This endpoint bills existing order lines — it does not create, reserve, consume, or otherwise move inventory. Inventory is governed by the sales order and its fulfillment, not by invoicing. On save, Distru recalculates the invoice's charge amounts and total and recomputes its payment status from recorded payments; for an update that lowers the total below what has already been paid, the excess is reconciled into a customer credit automatically.

Updates are sparse: any top-level field you omit is left unchanged, and sending an explicit null clears that field. The items and charges collections are optional on update — omit either to leave the existing line items or charges untouched. When you DO send items or charges, that array is the complete set for that collection: any existing entry whose id you leave out is deleted, and passing [] clears them all. A line item or charge sent WITH an id is patched — merged onto the stored row, so you can change one field and omit the rest; one WITHOUT an id is a new entry. If any part of the request is rejected (a bad order item, a validation failure), the whole upsert fails and nothing is changed.

A voided invoice is frozen and cannot be edited through this endpoint — the request is rejected. An invoice is voided automatically when its sales order is canceled (and un-voided if that order later leaves the canceled status), so voiding is driven by the order, not set here.

Side effects reach other systems asynchronously. A successful 200 means the invoice was saved, not that downstream syncs finished: if the company is connected to QuickBooks Online the invoice is queued for sync there, and if the invoice's customer maps to a connected point-of-sale (Treez, Dutchie, or Blaze) it is queued for sync to that POS. Poll the relevant system to observe the synced result. Distru may also email the invoice PDF to the customer when the order is configured to do so.

Required permission: invoices_permissions_create to create a new invoice, or invoices_permissions_edit (plus access to the invoice under team restrictions) to update an existing one.