Versioning & changelog
What can change, and how much warning you get.
API surface
The App API is versioned in the path: https://api.spuke.com/v1/app. A v1 route never changes meaning; incompatible redesigns ship as v2 and both run in parallel during the migration window.
Additive by default
These can ship any day without notice — build for them:
- new fields on existing objects
- new enum values (
status,reason,failure_code) - new event types
- new endpoints and new optional query parameters
Rules that keep you safe: ignore unknown fields, never fail on an unknown enum value, ignore unknown event types, never depend on field order or on the exact shape of an id.
Breaking changes
Removing a field, renaming one, changing a type, tightening a limit or retiring an event type are breaking. They are announced at least 90 days ahead by email to the developer contact, in the dashboard changelog and with a deprecation note in the affected docs page. During the window, both behaviours are available where technically possible.
App versions
Your own app is versioned separately: each submission freezes a listing plus a scope set. Published versions stay attached to the installations that consented to them, so adding a scope never silently widens an existing install — the merchant re-consents first.
Deprecation signals
Deprecated endpoints answer with a header for the whole notice period:
Spuke-Deprecation: true
Spuke-Sunset: 2026-12-01
Alert on that header in your logs — it is the earliest automated warning you get.
Changelog
The dashboard changelog lists every platform change with a date, a type (added / changed / deprecated / removed) and a migration note where one is needed. Subscribe to it from the developer dashboard.