API changelog and versioning — Italy
Date-stamped API versions, deprecation policy and recent changes — REST API for Italy.
Architecture — Versioning model for the Italy 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. SdI 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. IVA 22% and other Italy 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 SdI 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. Sistema di Interscambio (SdI) 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.
SdI channel changes?
Tracked in the same changelog. IVA 22% and other tax fields are stable in v1 and v2.