Versioning & Deprecation

This page explains how versions are structured, how long they are supported, and what actions developers should take when older versions are deprecated.

The ERPx API evolves to deliver new functionality, improved performance, and enhanced security.
To maintain stability for existing integrations, every change follows a defined versioning and deprecation.

API Versioning strategy

Version format

All ERPx API endpoints include a version number in the URI path:

https://host/v1/customers
https://host/v2/customers/2245

Version numbers are integers starting at 1. Each breaking change increments this number.

What triggers a new version?

Breaking changes (expect new version):

Changes to object structure.
Addition of required headers or properties.
Removal of properties, or headers.
Changes to resource meaning or calculation logic.
Changes to property data types (e.g., numeric to string).
New HTTP status codes.

Non-Breaking changes (no new version expected):

Addition of optional properties, query parameters, or headers.
New optional actions or endpoints.

Working with multiple versions

Backward compatibility

When building integrations:

You can add extra properties in requests - the API will ignore unknown fields.
You should expect new optional properties in responses - parse only what you need.
You should handle HTTP status codes generically by their series (2xx, 4xx, 5xx).
You should monitor the X-U4-Warning response header; it indicates that an endpoint is deprecated and scheduled for removal.

Discovering available versions

Check available API versions and their status:

GET https://host/v1/discovery/apis
GET https://host/v1/discovery/apis/latest

curl -X GET \
  "https://unit4-api-address/v1/discovery/apis?name=planner-postback
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \

[
 {
        "deprecationTime": "2025-12-31T00:00:00.000",
        "description": "Public API controller for Planner",
        "name": "planner-postback",
        "status": "Deprecated",
        "version": 2,
        "supportedVerbs": [
            "POST"
        ]
    },
    {
        "description": "Public API controller for Planner",
        "name": "planner-postback",
        "status": "Latest",
        "version": 3,
        "supportedVerbs": [
            "POST"
        ]
    }
]

Deprecation process

Timeline

When a version is deprecated:

Communication: Deprecation details are published on the Developer Portal and exposed through the Discovery API.
Grace Period: Minimum 6 months (two quarters) to migrate.
Sunset: After the grace period, the version is removed.

Deprecated version behaviour

Deprecated versions continue to function normally until sunset. Once sunset:

The API returns 410 Gone for all requests.
You must migrate to the current version to restore functionality.

Staying informed

Check the Swagger specification for deprecation notices.
Monitor the discovery endpoint for version status.

Migration support

When migrating between versions:

Review the release notes for breaking changes.
Test thoroughly in a non-production environment.
Update your integration incrementally.
Contact support if you need assistance or extension of deprecation timelines.

Best practices

Use the latest stable version for new integrations.
Monitor deprecation announcements to plan migrations.
Test with newer versions before deprecation deadlines.
Design clients to handle optional fields for easier upgrades.

U4 ERPx