> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /openapi.yaml post /entities/{entity_id}/migration/counters/advance openapi: 3.1.0 info: title: Arcus ERP Public API version: 1.0.0 description: > Arcus ERP public REST API. Designed for external integrations and data migration. **Authentication.** Bearer token (API key) via the `Authorization` header. Format: `Authorization: Bearer ark_live_ent__` (or `ark_test_*` for sandbox). API keys are issued per-entity in **Settings > Developers > API Keys**. **Entity scoping.** The entity is encoded in the API key prefix; routes are flat (e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform endpoints (migration, reconciliation, events, webhook endpoints, API keys) use the `/v1/entities/{entity_id}/...` form -- those are noted in their tags. **Key capabilities.** - Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource). - Cursor-based pagination (`starting_after` / `ending_before` / `limit`). - Idempotency via the `Idempotency-Key` header. - Webhook events for asynchronous notification. - Conditional requests / ETag for cache validation. servers: - url: https://api.arcuserp.com/v1 description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys) - url: https://dev-api.arcuserp.com/v1 description: >- Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev RDS) security: [] paths: /entities/{entity_id}/migration/counters/advance: post: tags: - Migration summary: Fast-forward number counters to source-system maximums description: > 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`. operationId: postMigrationCounterAdvance parameters: - name: entity_id in: path required: true schema: type: string format: uuid - name: Idempotency-Key in: header required: false schema: type: string description: > Optional idempotency key. If supplied, retrying the same call within 24 hours returns the previous result. requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/MigrationCounterAdvanceSingle' - $ref: '#/components/schemas/MigrationCounterAdvanceBatch' examples: single: summary: Single counter advance value: counter_type: invoice advance_to: 342665 batch: summary: Batch counter advance (all counters at cutover) value: counters: - counter_type: invoice advance_to: 342665 - counter_type: order advance_to: 250000 - counter_type: vendor_bill advance_to: 24044 responses: '200': description: Counter advance result content: application/json: schema: $ref: '#/components/schemas/MigrationCounterAdvanceResult' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' security: - ApiKeyAuth: [] components: schemas: MigrationCounterAdvanceSingle: type: object required: - counter_type - advance_to description: Single-counter advance payload. properties: counter_type: type: string description: > 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: type: integer minimum: 0 description: > New current_value for the counter. Next-issued = advance_to + 1. Must be >= existing current_value (monotonic; decrement not allowed). example: 342665 prefix: type: string maxLength: 20 description: > Required only when creating a new counter row (entity does not have one yet). Existing rows preserve their prefix. padding: type: integer minimum: 1 maximum: 12 description: | Optional. Used only when creating a new counter row. Defaults to 7. MigrationCounterAdvanceBatch: type: object required: - counters description: Batch advance payload (up to 50 counters per call). properties: counters: type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/MigrationCounterAdvanceSingle' MigrationCounterAdvanceResult: type: object description: > Result envelope for counter advance. Each row in `results` reports independently; a failure on one counter does not roll back the others. properties: object: type: string enum: - migration_counter_advance_result total: type: integer succeeded: type: integer failed: type: integer results: type: array items: $ref: '#/components/schemas/MigrationCounterAdvanceItem' MigrationCounterAdvanceItem: type: object description: Result for one counter advance attempt. properties: counter_type: type: string previous_value: type: integer description: current_value before the call (0 if newly created). current_value: type: integer description: current_value after the call. prefix: type: string padding: type: integer version: type: integer advanced: type: boolean description: > true if current_value changed; false on idempotent no-op (existing value already >= advance_to). next_issued_preview: type: string description: > Padded preview of the next-to-be-issued document number, e.g. "INV-342666". error: type: string description: Present only on failure (validation, conflict, etc.). code: type: string description: Machine-readable error code. ErrorEnvelope: type: object description: | Canonical error response envelope. All API errors use this shape. required: - error - code properties: error: type: string description: Machine-readable error key example: not_found code: type: string description: Machine-readable error code (often same as error) example: not_found type: type: string enum: - validation_error - permission_error - not_found - conflict - rate_limit - internal - expand_error - not_implemented example: not_found hint: type: string description: Human-readable one-sentence explanation (English) example: >- The requested order does not exist or does not belong to this entity. param: type: string description: The parameter that caused the error, if applicable example: expand[0] required: type: string description: The scope required (only on insufficient_scope errors) example: accounts:read request_id: type: string description: >- Unique request ID for support tracing (maps to CloudWatch log stream) example: req_abc123 responses: Error: description: Error response (400/401/403/404/409/422/429/500) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: | 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. ````