Set recovered historical payment balance on migrated purchase orders
Order-side sibling of vendor-bills/set-historical-balance. On a Versa
migration a settled purchase order’s payment state is not always carried
verbatim into the imported orders row, so a migrated historical PO can
land showing balance_due = NULL or payment_status = unpaid even when
the underlying bill was fully paid. The loader’s 6.4c post-pass derives
the recovered amount_paid / balance_due / payment_status per PO and
POSTs the resolved values here so the procurement view ties to the settled
truth.
GL-NEUTRAL. A purchase order posts no journal entry of its own (the vendor bill / GRNI does). This endpoint sets the three order-level payment columns only and never posts or touches a journal entry.
Lookup key. Each item resolves the migrated PO by po_id
(orders.id, preferred) OR external_id (orders.external_id, the loader’s
String(versa order_id) fallback).
Strict provenance. Only rows with document_type = 'purchase_order'
AND external_source = 'versa_cloud' AND is_historical_import = true
are touched. No live operator PO is ever modified.
Clamp. amount_paid is clamped to order_total;
balance_due = max(0, order_total - amount_paid); payment_status is
recomputed (paid / partial / unpaid) from the clamped numbers.
Idempotent. An already-at-target PO (within a cent + same status)
returns set=false (no-op). Re-running the whole pass is safe.
Scope: migration:write. Max 500 items per call.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Headers
Optional idempotency key. If supplied, retrying the same call within 24 hours returns the previous result.
Path Parameters
Body
500
