Change Management API Documentation

Overview

This document outlines how we manage changes to our API and communicate them to our integrators. We are committed to providing a stable, reliable API while continuously improving our services. Understanding our change management process will help you plan your integrations and stay informed about updates.

Change Categories

1. Breaking Changes 🚨

Definition: Changes that require modifications to existing integrations and may cause failures if not addressed.

Examples:

• Changing required parameters
• Altering existing response structures or data types
• Changing existing error codes

Impact: High - Requires code changes in your integration

Communication & Timeline:

• Advance Notice: 6 months before implementation
• Channels: Email notification and Changelog
• Information Provided:
  • Detailed migration guide
  • Code examples for before/after scenarios

2. Backwards-Compatible Additions ✨

Definition: New features or capabilities that don't affect existing functionality.

Examples:

• New endpoints
• Additional optional parameters
• New response fields (additive only)
• New webhook events
• Additional authentication methods

Impact: None - Existing integrations continue to work unchanged

Communication & Timeline:

• Notice: Upon release
• Channels: Changelog
• Information Provided:
  • Feature documentation
  • Use case examples

3. Deprecations ⚠️

Definition: Features marked for future removal but still functional.

Examples:

• Endpoints scheduled for retirement
• Parameters being phased out
• Legacy authentication methods

Impact: Medium - Future action required, but immediate functionality maintained

Communication & Timeline:

• Advance Notice: Minimum 6 months
• Channels: Email notification, API response headers, changelog
• Information Provided:
  • Deprecation timeline
  • Recommended alternatives
  • Migration path
  • Deprecation warnings in API responses

4. Bug Fixes 🐛

Definition: Corrections to unintended behavior.

Examples:

• Fixing incorrect response data
• Resolving edge case errors
• Correcting documentation inaccuracies

Impact: Low to Medium - May affect integrations relying on incorrect behavior

Communication & Timeline:

• Notice: Upon fix deployment
• Channels: Changelog, and our status page for critical fixes
• Information Provided:
  • Description of the issue
  • What was fixed
  • Any potential impact on integrations

5. Documentation Updates 📚

Definition: Improvements or clarifications to API documentation without functional changes.

Examples:

• Additional code examples
• Clarified descriptions
• New guides or tutorials
• Corrected typos or errors

Impact: None - Informational only

Communication & Timeline:

• Notice: Immediate upon publication
• Channels: Changelog
• Information Provided:
  • Summary of updates
  • Links to updated sections

6. Regulatory changes 🧑‍⚖️

Definition: Changes imposed by regulatory bodies (Government, OpenPeppol, BOSA)

Examples:

• Regular updates of the Peppol BIS Billing v3 ruleset: see here
• PSD2/PSD3 compliance

Impact: Generally High - Although their impact is generally big, these changes are often announced sufficiently in advance.

Communication & Timeline:

• Notice: Advance notice as soon as we are informed
• Channels: Changelog and Email notification depending on the scope
• Information Provided:
  • Migration guide if applicable
  • Summary of the impact
  • Links to the updated sections in our documentation

7. Maintenance 🔒

Definition: Actions done in order to keep our infrastructure up to date and secure

Examples:

• Upgrading database engine
• Securing endpoints

Impact: High - Downtime is expected but announced and not during office hours (no impact on our documentation)

Communication & Timeline:

• Notice: In advance notice through our status page (only for our production environment)
• Channels: Our status page
• Information Provided:
  • Date, time and duration of planned maintenance
  • Affected services

🚧

Regular automated maintenance may occur every Tuesday from 1:00 AM to 3:00 AM GMT

Communication Channels

Primary Channels

• Email Notifications: For breaking changes and deprecations
• Changelog: Comprehensive record of all changes at /changelog
• API Response Headers: Deprecation warnings and version information

Supplementary Channels

• Status Page: For service impacts and maintenance

Best Practices for Integrators

1. Subscribe to Notifications: Ensure you're receiving emails for your integration
2. Review Changelog Regularly: Visit our changelog monthly
3. Test in Staging: Validate changes in non-production environments first
4. Plan for Migrations: Allocate time for breaking changes well before deadlines

Support

If you have questions about any changes:

• Email: [email protected]