curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/migration/jobs/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "queue_cleanup_2026_05_22_abandoned_for_new_entity"
}
'

{
  "object": "migration_jobs_cancel_result",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cancelled": 123,
  "job_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "reason": "<string>",
  "include_running": true
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Migration

Cancel pending (and optionally running) migration jobs for an entity

Operational queue cleanup. Sets status='cancelled' on every pending migration job for the entity, and (optionally) every running job. A cancelled job is distinct from a failed job: monitoring should not treat it as an error, and the audit reason is recorded in the job’s errors[] JSONB so the cancellation context is preserved.

Common use cases:

The entity is being abandoned for a fresh entity, so the queue is contaminated.
A buggy bulk-submit needs to be drained before a clean re-run.
The runner is being redeployed and in-flight jobs should not be claimed mid-update.

Body parameters.

reason (optional string) — audit note stored in each cancelled job’s errors array. Defaults to "admin_cancelled".
include_running (optional boolean) — also cancel running jobs. Default false. Risky for live runs (cancels in-flight work); use only when you’ve confirmed nothing meaningful is in flight.

Scope: migration:write.

POST

entities

{entity_id}

migration

jobs

cancel

curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/migration/jobs/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "queue_cleanup_2026_05_22_abandoned_for_new_entity"
}
'

{
  "object": "migration_jobs_cancel_result",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cancelled": 123,
  "job_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "reason": "<string>",
  "include_running": true
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

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.

Path Parameters

entity_id

string<uuid>

required

Body

application/json

reason

string

Audit note stored in each cancelled job's errors[] JSONB. Defaults to 'admin_cancelled'.

Example:

"queue_cleanup_after_entity_abandoned"

include_running

boolean

default:false

Also cancel 'running' jobs. Default false. Risky for live runs.

Example:

false

Response

Cancel result with the list of cancelled job IDs

object

enum<string>

Available options:

migration_jobs_cancel_result

entity_id

string<uuid>

cancelled

integer

Number of jobs transitioned to 'cancelled'.

job_ids

string<uuid>[]

IDs of jobs that were cancelled (in created_at order).

reason

string

include_running

boolean

Fast-forward number counters to source-system maximums Relink migrated JE source_id to Arcus order/invoice UUIDs