Skip to main content

​
Overview

The Arcus API is versioned by date. When a breaking change ships, a new version date is published and the previous version continues to work for at least 12 months. This lets you adopt changes on your own schedule without emergency upgrades. Non-breaking changes (new fields, new optional parameters, new endpoints, new enum values) are added to the current version without a new version date.

​
Specifying a version

Pass the Arcus-Version header on every request:
If you omit the header, the API uses the version your API key was created on. This default ensures existing integrations do not break when new versions ship. The header applies to every call, reads and writes alike. The same header on a create call looks like this:
document_type is the one required field on an order create; send account_id for any order that belongs to a customer. See Creating orders for the rest of the body.

​
Current version

The current stable version is 2026-05-01. This is the version the initial API endpoints were published on.

​
Version history

​
What counts as a breaking change

Arcus follows a strict definition of “breaking” to avoid unnecessary version bumps: Breaking (requires new version):
  • Removing a field from a response
  • Changing a field’s type (string -> integer, UUID -> slug)
  • Changing HTTP status codes on success paths
  • Removing an endpoint
  • Changing required fields on a request body
  • Changing filter parameter semantics
Non-breaking (added to current version):
  • New optional request fields
  • New response fields
  • New endpoints
  • New enum values (your code must handle unknown enum values gracefully)
  • New optional headers
  • New error codes on existing error types

​
Be explicit about defaults that can narrow

A request that leaves a filter out relies on a default, and a default can be tightened to match what Arcus itself shows. List orders is the example to know: with no document_type, it returns only the sales-side documents, which are quotes, sales orders and invoices. Returns, purchase orders and late-fee invoices are still available, but only when you ask for them:
document_type accepts quote, sales_order, invoice, return, purchase_order and late_fee_invoice. An integration that needs a specific population should always send the filter rather than lean on the default. Before July 31, 2026 the default list also included returns, so an integration written against that behavior should add document_type=return where it still expects them.

​
SDK version pinning

SDKs are versioned independently from the API. SDK patch releases are always safe to apply. SDK minor releases may add new API version support. SDK major releases may drop support for deprecated API versions.

​
Upgrading to a new version

  1. Read the changelog for the new version
  2. Update the Arcus-Version header in your test environment
  3. Run your integration tests
  4. Fix any breaking changes in a dev/staging deploy
  5. Update the header in production
The SDK’s arcusVersion config option sets the header for all requests: