API changelog and versioning — Poland
Date-stamped API versions, deprecation policy and recent changes — REST API for Poland.
Architecture — Versioning model for the Poland API
We use date-stamped API versions: Accept-Version: 2026-03-15. Within a version, changes are additive only (new fields, new endpoints, new enum values behind opt-in flags). Breaking changes ship as a new dated version. Your account is pinned to the version active at signup unless you explicitly upgrade. KSeF channel changes are versioned separately and surfaced in the invoice payload.
How to wire it up — Deprecation policy
Deprecations are announced ≥12 months in advance via three channels: dashboard banner, monthly changelog email, and a Sunset response header on affected endpoints. We never silently remove fields. At end-of-life the old version returns 410 Gone with a Link header to the migration guide. VAT 23% and other Poland tax fields are stable in v1 and v2.
Operations and edge cases — Recent changes (excerpt)
2026-03-15: added partial_ok on orders, new order.partially_shipped event. 2026-01-10: added KSeF acknowledgement id in invoice payload. 2025-11-04: idempotency keys now required on POST /v1/orders (breaking; v2). Full changelog at /docs/changelog with RSS and Atom feeds. Krajowy System e-Faktur (KSeF) schema additions are non-breaking in pinned versions.
FAQ
How are versions pinned?
Account default at signup; per-request override via Accept-Version. Test the new version with a header before changing the account default.
How do you announce changes?
Dashboard banner, monthly email and a Sunset response header on affected endpoints. We never silently change behaviour in a pinned version.
Is there an RSS feed?
Yes — /docs/changelog.rss and an Atom feed at /docs/changelog.atom.
How long are old versions supported?
Minimum 24 months from successor release; 12-month deprecation notice before end-of-life.
KSeF channel changes?
Tracked in the same changelog. VAT 23% and other tax fields are stable in v1 and v2.