Skip to main content

Settle Whole PO Billing

POST 
/api/purchase-orders/:purchase_order/settle-billing

Bulk-settle the billing axis for every eligible line on a purchase order in one call — the whole-PO equivalent of the per-line settle endpoint. Each still-open, short-billed line is stamped billing-settled; lines already fully invoiced or already settled are left untouched.

Required scope: purchase-orders:write

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

Authentication: Requires Bearer token. Requires the purchase_orders.update permission.

Request body fields:

  • reason (optional, nullable, string, max 500): free-text note recorded on every line settled by this call.
  • kind (optional, string): how the lines are being settled. final_invoice (default) records that the supplier's final bill is in and no more bills will follow; billed_outside_sku records that the supplier's bill already exists in your accounting provider only (a transition-period bill entered there before your ledger began, or one reconciled to a card or wire payment there), so the received-not-invoiced accrual is released from the settlement date without creating a bill; not_billable records an over-receipt nobody will ever bill (a fulfilment centre over-counted or mis-scanned the shipment while the supplier's invoice covers everything it shipped), releasing the accrual from the settlement date in the same way.
  • settled_at (optional, date): the settlement's effective date. Defaults to now. For billed_outside_sku pass the provider bill's date; for not_billable pass the date the over-count was recognised. The purchase clearing report honours this date: the line leaves the goods-received-not-invoiced position from that day.

After settling, the purchase order's invoice_status is re-derived and returned.

Response fields:

  • settled_count: number of lines newly billing-settled by this call.
  • purchase_order: { id, invoice_status, fully_invoiced } after re-derivation.
  • lines[]: the billing-settlement view of each line that was settled (each with billing_settlement_kind, billing_settled_by and purchase_order).

Request​

Responses​

OK