Geldstuck uses URI-based major versions and dated minor versions. The major version is in the path; the minor is a header. Breaking changes always bump the major.

​
Current version

  • Major: v1 - all paths are prefixed with /v1.
  • Latest minor: 2026-04-01.

​
Pinning a minor version

Pass the Geldstuck-Version header to lock your integration to a specific dated release: 
Geldstuck-Version: 2026-01-15
Without the header, we default to the version your account was created against. Pinning is recommended - it makes upgrades an explicit decision. 
curl https://api.geldstuck.com/v1/tenants/me \
  -H "x-api-key: $GELDSTUCK_PUBLIC_KEY" \
  -H "x-api-secret: $GELDSTUCK_SECRET_KEY" \
  -H "Geldstuck-Version: 2026-04-01"
Pin the version in one place - your HTTP client helper - so every outbound call inherits it.

​
What counts as a breaking change?

We bump the major version (e.g., v1 → v2) when any of the following happen:
  • An endpoint is removed.
  • A required field is added to a request body.
  • A field in a response changes type or meaning.
  • Default behavior changes in a way that existing clients wouldn’t expect.
We bump the minor version for:
  • New endpoints or new fields.
  • New enum values on existing fields.
  • New webhook event types.
  • Performance-only behavior changes.
We do not consider adding a new enum value a breaking change. Your code should treat unknown values as “something new” and log rather than crash.

​
Upgrading

1

Read the changelog

/changelog documents every dated release with diffs and migration notes.
2

Test in sandbox

Pin your sandbox to the new version while keeping production on the old one.
3

Roll out

Once tests pass, flip production’s pinned version. No redeploy needed - it’s just a header.

​
Deprecation policy

When a feature is deprecated, we commit to:
  • 6 months of overlap where old and new both work.
  • A Deprecation response header flagging affected endpoints.
  • A minimum of one email to every integration owner before turn-off.