Every REST endpoint in Acumatica carries an explicit version number in its URL — /entity/Default/24.200.001/SalesOrder. That number isn't cosmetic. It's what lets Acumatica ship platform upgrades without breaking every integration pointed at the instance, as long as you version deliberately instead of always pointing at whatever the newest default happens to be.
What the version number actually pins
The version segment pins the contract — the exact set of fields, entities, and actions that endpoint exposes — independent of the underlying Acumatica platform build. Multiple contract versions of the Default endpoint can exist side by side on the same instance; upgrading Acumatica itself doesn't retroactively change what an older contract version returns. This is the mechanism that makes "the platform upgraded and my integration broke" avoidable rather than inevitable.
The Default-endpoint trap
Pointing an integration at Default with whatever version happened to be current when you built it is the most common mistake. It works fine until an Acumatica platform upgrade introduces a newer default contract version, someone regenerates or reconfigures endpoints, or a field that used to be in the default set gets reorganized — and the integration breaks with no code change on your side to point to.
Don't add custom fields directly onto the Default endpoint. Clone it into a named endpoint (MyIntegration, version 1.0) from the Web Service Endpoints screen, and make your changes there. That contract is yours to control the lifecycle of — nobody else's upgrade or reconfiguration touches it out from under you.
Planning a version upgrade deliberately
When you do need a new field or entity that requires a newer contract version, treat it like any other dependency bump: stand up the new version alongside the old one, point a test client at it, confirm field names and nested structures still parse the way your code expects (they don't always carry over 1:1 across major contract revisions), and only cut traffic over once you've verified behavior — don't edit the version number in a live integration's config and find out what broke in production.
Keeping old versions alive during migration
Because multiple versions of the same endpoint can coexist, there's no reason to force a hard cutover. Keep the old contract version active until every consumer — including ones you might have forgotten about, like an old scheduled export or a partner's system calling in — has moved to the new one. Killing an old endpoint version prematurely is a self-inflicted outage, not an upgrade.
Tracking what actually changed between versions
Acumatica's release notes call out contract changes per version, but the more reliable check is diffing the generated OpenAPI/Swagger document for the old and new version side by side — it shows you exactly which fields, entities, and actions changed rather than relying on prose release notes to have mentioned the specific field your integration depends on.
Wrapping up
Version pinning exists precisely so platform upgrades don't have to be integration outages. Clone the default endpoint instead of editing it directly, treat a version bump as a planned migration rather than a config tweak, and keep old contract versions alive until every consumer has actually moved off them.
Independent software engineer in Nairobi specialising in Acumatica customisations, Laravel backends, and tax fiscalisation integrations across East and Southern Africa.