Skip to main content

Migration guide template

Use this template when ProcureIQ publishes a new major API version and developers need a clear upgrade path.

Overview​

  • Current version: v1
  • Target version: v2
  • Deprecation announced: YYYY-MM-DD
  • Sunset date: YYYY-MM-DD

Breaking changes​

List every breaking change in plain English.

For each one, explain:

  • what changed
  • who is affected
  • what the new behavior is
  • what the integrator needs to do

Example format:

  • displayPriceFormatted has been removed from GET /api/v1/products
  • use displayPriceLocale instead

Updated endpoints​

List endpoints that still exist but changed behavior, payload shape, auth requirements, or field names.

Recommended format:

  • GET /api/v1/products -> GET /api/v2/products
  • POST /api/v1/orders -> POST /api/v2/orders

For each endpoint, include:

  • old request example
  • new request example
  • old response example
  • new response example

Removed endpoints​

List endpoints that were removed completely and explain what replaced them, if anything.

Example:

  • GET /api/v1/legacy-search removed
  • replacement: POST /api/v2/search/sessions

New features​

Summarize the benefits of the new version so teams understand why the migration is worth doing.

Examples:

  • more consistent pagination
  • better webhook idempotency fields
  • clearer payment status objects
  • stronger OAuth scope controls

Migration checklist​

Provide a simple checklist teams can work through.

Example:

  • update base URL from /api/v1 to /api/v2
  • update OAuth scopes if required
  • replace removed response fields
  • update webhook signature verification if headers changed
  • test all critical workflows in staging
  • deploy production changes before the sunset date

Support and troubleshooting​

Tell integrators where to get help.

Include:

  • changelog link
  • migration guide owner or support address
  • support ticket link
  • developer newsletter sign-up link