Relink migrated JE source_id to Arcus order/invoice UUIDs
A migrated historical journal entry is born with source_id holding the
source-system (Versa) document INTEGER, because historical GL is loaded
BEFORE orders/invoices: the Arcus order/invoice UUID does not exist yet.
Native Arcus order JEs set source_id = the Arcus order UUID, and the
GL UI / reports resolve the source document by that UUID.
This endpoint is the corrective reconciliation pass run AFTER orders and
invoices are migrated. The caller supplies a batch of items, each
mapping a source-system journal id (external_id, carried on
journal_entries.external_id) to its Arcus order/invoice UUID
(source_id).
Strict-resolve safety. source_id must be a UUID that resolves to
an order in the entity (or a vendor_bill when source_module=‘ap’ or
new_source_type is AP_BILL / AP_PAYMENT, added 2026-05-27). A non-UUID
or non-resolving value is rejected, never written — this prevents
re-stamping a source-system integer or mislinking across entities.
Idempotent. When a JE already carries the target source_id
(and the target source_type and description match), the item
returns relinked=false (no-op). Re-running the whole pass is safe.
Scope guard (relaxed 2026-05-27 MIGRATION-MAPPING-NATIVE). Only
journal_entries whose external_source = 'versa_cloud' can be
matched. Previously also required source_type = VERSA_MIGRATION;
relaxed so the handler can relink rows that the loader has already
classified to canonical source_types (PAYMENT, INVOICE, AP_BILL, etc).
is_historical_import is asserted as a belt-and-suspenders guard.
Native Arcus JEs (external_source IS NULL) are never matched.
Optional source_type upgrade (new_source_type, added 2026-05-27).
When supplied, upgrades source_type from VERSA_MIGRATION to a
canonical Arcus value. The handler never downgrades a canonical
source_type back to the fallback.
Optional description enrichment (enrich_description, added 2026-05-27).
When true, rebuilds description from the canonical native template
with the order_number suffix. Non-order-attached source_types
(INVENTORY_ADJUSTMENT / MANUAL / BANK_RECON / BANK_DEPOSIT) are skipped
to preserve the Versa memo carried by the loader.
Pure header UPDATE. Touches only journal_entries.source_id,
source_module, source_type, and description. No line is touched,
no amount is touched, no FK is created or dropped.
Scope: migration:write.
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
Batch JE source-relink payload (up to 500 items per call).
1 - 500 elementsResponse
JE source-relink result
Result envelope for JE source relink. Each row in results reports
independently; a failure on one item does not roll back the others. Pure
column UPDATE on the JE header (source_id / source_module / source_type /
description). No line is touched and no amount is touched.
migration_je_source_relink_result Total per-batch count of rows where source_type was upgraded from VERSA_MIGRATION to a canonical value. Added 2026-05-27.
Total per-batch count of rows where the description was rebuilt to the canonical native template. Added 2026-05-27.

