Skip to content

API policy

API versioning and deprecation policy

How the Peppol API changes: which changes arrive without notice, how much notice a breaking change gets, and how the API tells you.

Versions

The version of the API is in the path: /v1. The base URLs are https://api.peppol.sh/v1 (live) and https://sandbox.peppol.sh/v1 (sandbox).

Changes without notice

These changes are not breaking. We can release them in /v1 at any time:

  • New endpoints.
  • New optional request fields.
  • New response fields.
  • New error codes.

Write your client so that it ignores response fields it does not know, and so that it handles an error code it does not know.

Breaking changes

For a breaking change, or for the removal of an endpoint in /v1, we give a notice of 6 months minimum. Examples of a breaking change are the removal of a response field, a new required request field, or a different type for a field.

How the API tells you

During the notice period:

  • The operation is marked deprecated: true in the OpenAPI spec.
  • Its responses include a Deprecation header (RFC 9745) with the date on which the operation became deprecated.
  • Its responses include a Sunset header (RFC 8594) with the date after which the operation can stop.
  • Its responses include a Link header to this page, with rel="deprecation".
  • The notice is published on this page.
Example of the headers, not a real notice
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://peppol.sh/deprecation>; rel="deprecation"

Current notices

No operation is deprecated, and no removal is scheduled.

One request field has a replacement: lines[].discount. The spec marks it deprecated: true to tell you to use lines[].allowances in new integrations. This is advice and not a notice: the field continues to work, it has no Sunset date, and a removal would first get the notice of 6 months on this page.

Questions

Email hello@peppol.sh, or see the contact page and the developer page.