Skip to main content

ProcureIQ API versioning policy

ProcureIQ uses URI versioning for the public API. That means every stable API version has its own base path.

Current stable version​

The current stable public API version is:

/api/v1/

Future major versions will follow the same pattern:

  • /api/v2/
  • /api/v3/
  • and so on

What triggers a new major version​

ProcureIQ creates a new major API version when a change would break existing integrations.

Examples of breaking changes include:

  • removing a field from a response
  • renaming an existing field
  • changing a field type in an incompatible way
  • tightening validation so previously valid requests fail
  • removing an endpoint
  • changing authentication behavior incompatibly
  • changing webhook payload meaning in a way that breaks existing consumers

If a change would break existing client code, it belongs in a new major version such as v2.

What does not require a new major version​

Not every API improvement is breaking. ProcureIQ may add non-breaking changes to the current stable version.

Examples include:

  • adding new optional fields to responses
  • adding new optional query parameters
  • adding new endpoints
  • adding new webhook event types
  • adding new enum values where clients are already expected to handle forward-compatible values

These changes can ship in the current version because well-behaved clients should continue working without modification.

Support window for deprecated versions​

When ProcureIQ deprecates an API version, that version will remain supported for a minimum of 12 months after the deprecation announcement.

This gives integrators time to:

  • review the migration guide
  • test against the newer version
  • update production workflows safely

Deprecation notice period​

ProcureIQ will announce deprecations at least 6 months before removal.

That notice period is the minimum. In practice, major customers or sensitive integrations may receive more advance notice where possible.

Deprecation headers​

When a specific endpoint is deprecated, ProcureIQ adds headers to the HTTP response so clients and monitoring tools can detect the change automatically.

You may see headers like:

Deprecation: true
Deprecated: true
Sunset: Sat, 31 Dec 2026 00:00:00 GMT
Link: <https://docs.procureiq.com/api/migration-v2>; rel="successor-version"

What these headers mean​

  • Deprecation or Deprecated: the endpoint is deprecated
  • Sunset: the planned removal date
  • Link: the migration guide or successor-version documentation

If your integration sees these headers, treat them as an action item for your engineering team.

How ProcureIQ announces version changes​

ProcureIQ communicates API version changes through:

  • the public changelog endpoint
  • documentation updates on docs.procureiq.com
  • deprecation headers on affected endpoints
  • developer newsletter release summaries

If you run a production integration, it is a good idea to subscribe to the developer newsletter and monitor the changelog regularly.

Best practices for integration teams​

To make version upgrades smoother:

  • avoid assuming response objects will never gain new fields
  • handle unknown enum values safely where possible
  • log response headers so deprecation notices are visible
  • test against staging before upgrading to a new version
  • build webhook consumers to ignore unknown event fields instead of failing

Migration planning​

When ProcureIQ publishes a new major version, use the migration guide for that version transition. A standard migration guide includes:

  • breaking changes
  • updated endpoints
  • removed endpoints
  • new features
  • a migration checklist

For the standard structure we use internally, see Migration Template.