Retroactively remap Versa-migration 8xxx leaves to Arcus native GL accounts

Retroactive cleanup helper for entities loaded with the under-covered Phase 5A fold-rule set. For each item, transactionally swaps every journal_entry_lines.gl_account_id reference from FROM to TO, then optionally soft-deletes the FROM account.

Safety invariants (HARD BAR).

• Both accounts must belong to the API key’s entity.
• FROM must be a Versa-migration leaf: description must contain versa_real_id= or “Migrated from Versa”. Native Arcus accounts never carry this tag, so this gate prevents the handler from ever touching a native account.
• TO must have system_account_key NOT NULL (must be a native Arcus account; remapping one 8xxx leaf to another is rejected).
• Per-pair transaction with SELECT ... FOR UPDATE locks on both accounts.
• Pre/post snapshot of journal_entry_lines.count + SUM(debit) + SUM(credit) for FROM is compared against TO’s delta; mismatch aborts the transaction so TB never drifts.

soft_delete_source. Optional. When true AND zero JE lines remain pointing at FROM after the UPDATE (verified in-transaction), the source account is soft-deleted with deleted_at = NOW() and is_active = false. When a concurrent writer adds a JE line to FROM between the UPDATE and the orphan check, the soft-delete is skipped (the swap still committed).

Max 50 items per call (smaller cap than relink because each item locks the gl_account row + UPDATEs every JE line on it; large batches risk lock contention with concurrent posters).

Scope: migration:write.

POST /entities/{entity_id}/migration/gl-accounts/remap

Retroactively remap Versa-migration 8xxx leaves to Arcus native GL accounts

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/migration/gl-accounts/remap \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "from": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "soft_delete_source": false
    }
  ]
}
'

200

{
  "object": "migration_gl_account_remap_batch",
  "total": 123,
  "succeeded": 123,
  "failed": 123,
  "total_je_lines_moved": 123,
  "total_sources_soft_deleted": 123,
  "results": [
    {
      "from": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status_code": 123,
      "moved": 123,
      "source_soft_deleted": true,
      "error": "<string>",
      "code": "<string>",
      "hint": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

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

Idempotency-Key · string

Path Parameters

entity_id · string<uuid> · required

Body

application/json

items · object[] · required

Required array length: 1 - 50 elements

Show child attributes

Response

200

application/json

GL-account remap batch result

object · enum<string>

Available options: migration_gl_account_remap_batch

total · integer

succeeded · integer

failed · integer

total_je_lines_moved · integer

total_sources_soft_deleted · integer

results · object[]

Show child attributes