Skip to main content

Auto-Link Inbound Shipments

POST 
/api/purchase-invoices/:purchaseInvoice/inbound-shipments/auto-link

Run the shipment matcher for this purchase invoice now. No request body is required.

Required scope: purchase-orders:write

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

Every inbound shipment on the invoice's purchase order that is not yet linked to it is weighed against the invoice's lines. A shipment whose lines all match this invoice's lines unambiguously (exact) is linked immediately — exactly as Link Inbound Shipment to Invoice would, but recorded with linked_via = auto. The rest are only reported: partial means some overlap but an ambiguity a person must resolve (a purchase order line billed by two lines on this invoice, a shipment line already paired to a line on another invoice, a shipment line missing from this invoice, or a shipment unlinked from this invoice earlier); none means the shipment has no line in common with the invoice. Both remain linkable by hand.

This runs even when the account-level purchase_invoice_auto_link_shipments setting is off — that setting only controls whether matching happens on its own as invoices and shipments are saved; auto_link_enabled in the response reports it. The same guarantees as a manual link apply: a manually set due date is never overwritten, and a paid invoice's due date never moves.

Response data:

  • linked — the shipments this run linked
  • suggested — the partial shipments left for a person to decide
  • candidates — every shipment considered, with match (exact, partial, none) and a match_reason in plain words
  • auto_link_enabled — the account-level automatic matching setting
  • due_date (YYYY-MM-DD or null), due_date_source (derived, manual, none) and due_date_basis — the invoice's due date after the run and where it came from (same shape as on Get Purchase Invoice)

message reads "Inbound shipment updated successfully" when at least one shipment was linked, otherwise "No shipment matched this bill unambiguously."

Authentication: Requires Bearer token.

Request​

Responses​

OK