Relink migrated inventory transaction reference_id to Arcus order UUIDs
A migrated historical inventory transaction is born with reference_id = NULL
because Phase 6 (orders/invoices) runs concurrently or after Phase 4 (inventory
transactions); the Arcus order UUID does not exist yet at ITX-insert time.
Native Arcus order fulfillments set reference_id = the Arcus order UUID, and
the per-order drill-through resolves inventory movements via that UUID.
This endpoint is the corrective reconciliation pass (Phase 9c) run AFTER orders
and invoices are migrated. The caller supplies a batch of items, each mapping
the Versa source transaction id (external_id, carried on
inventory_transactions.transaction_id) to its Arcus order UUID (source_id).
Lookup key. The column inventory_transactions.transaction_id holds the
Versa source transaction id (set by recordHistoricalInventoryTransaction).
There are no external_source / external_id columns on this table.
Strict-resolve safety. source_id must be a UUID that resolves to an order
in the entity. A non-UUID or non-resolving value is rejected, never written.
Idempotent. When an ITX already carries the target reference_id, the item
returns relinked=false (no-op). Re-running the whole pass is safe.
Provenance guard. Only ITXs with reference_type = 'versa_migration' can
be relinked. Native Arcus ITXs are never matched.
Pure UPDATE. Touches only inventory_transactions.reference_id. No quantity,
cost, balance, or FIFO layer is modified.
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 ITX source-relink payload (up to 500 items per call).
1 - 500 elementsResponse
ITX source-relink result
Result envelope for ITX source relink. Each row in results reports
independently; a failure on one item does not roll back the others. Pure
column UPDATE on reference_id. No quantity, cost, balance, or FIFO layer
is modified.

