API changelog and versioning — Spain
Date-stamped API versions, deprecation policy and recent changes — REST API for Spain.
Architecture — Versioning model for the Spain 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. FACe/SII 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 21% and other Spain 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 FACe/SII 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. FACe / Suministro Inmediato de Información (SII) 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.
FACe/SII channel changes?
Tracked in the same changelog. IVA 21% and other tax fields are stable in v1 and v2.