curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/migration/counters/advance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "counter_type": "invoice",
  "advance_to": 342665
}
'

{
  "object": "migration_counter_advance_result",
  "total": 123,
  "succeeded": 123,
  "failed": 123,
  "results": [
    {
      "counter_type": "<string>",
      "previous_value": 123,
      "current_value": 123,
      "prefix": "<string>",
      "padding": 123,
      "version": 123,
      "advanced": true,
      "next_issued_preview": "<string>",
      "error": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "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"
}

{
  "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

Fast-forward number counters to source-system maximums

Advances Arcus number_counters.current_value past the source system’s last issued document number, so the first post-cutover document does not collide with migrated documents. Used at the end of a data migration before the cutover handoff.

Semantics. advance_to is the new current_value (NOT the next-issued number). The next-issued number will be advance_to + 1, padded with the counter’s existing prefix and padding. Example: if Versa’s last invoice was INV-342665, set advance_to: 342665 and Arcus’s next invoice will be 342666.

Monotonic guarantee. advance_to must be greater than or equal to the existing current_value. Decrementing is not allowed (Rule 23 SSOT). If the existing value already meets or exceeds advance_to, the call is a no-op (idempotent; advanced=false in the response).

Single or batch. Either pass {counter_type, advance_to} for a single counter, or {counters: [...]} for up to 50 counters in one call. Each counter’s result is returned independently; a failure on one does not roll back the others.

New counter creation. If a counter row does not exist for the entity, the endpoint inserts one. prefix is required in that case; padding defaults to 7.

Scope: migration:write.

POST

entities

{entity_id}

migration

counters

advance

curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/migration/counters/advance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "counter_type": "invoice",
  "advance_to": 342665
}
'

{
  "object": "migration_counter_advance_result",
  "total": 123,
  "succeeded": 123,
  "failed": 123,
  "results": [
    {
      "counter_type": "<string>",
      "previous_value": 123,
      "current_value": 123,
      "prefix": "<string>",
      "padding": 123,
      "version": 123,
      "advanced": true,
      "next_issued_preview": "<string>",
      "error": "<string>",
      "code": "<string>"
    }
  ]
}

{
  "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"
}

{
  "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.

Headers

Idempotency-Key

string

Optional idempotency key. If supplied, retrying the same call within 24 hours returns the previous result.

Path Parameters

entity_id

string<uuid>

required

Body

application/json

Option 1
Option 2

Single-counter advance payload.

counter_type

string

required

One of the counter_type enum values: order, invoice, quote, po, rma, journal, account, vendor_bill, ap_payment, check, transfer, vendor_return, refund, inventory_txn, work_order, fixed_asset, lease, lease_payment, deposit, vendor_credit, payment_batch.

Example:

"invoice"

advance_to

integer

required

New current_value for the counter. Next-issued = advance_to + 1. Must be >= existing current_value (monotonic; decrement not allowed).

Required range: x >= 0

Example:

342665

prefix

string

Required only when creating a new counter row (entity does not have one yet). Existing rows preserve their prefix.

Maximum string length: 20

padding

integer

Optional. Used only when creating a new counter row. Defaults to 7.

Required range: 1 <= x <= 12

Response

Counter advance result

Result envelope for counter advance. Each row in results reports independently; a failure on one counter does not roll back the others.

object

enum<string>

Available options:

migration_counter_advance_result

total

integer

succeeded

integer

failed

integer

results

object[]

Show child attributes

Overview

All Endpoints

Fast-forward number counters to source-system maximums

Authorizations

Headers

Path Parameters

Body

Response