API Versioning

How Watenga versions its API, what counts as a breaking change, and how to upgrade safely.

How Watenga Versions Its API

Watenga's current API version is 2026-01-01. Every API app you create in the Developer Dashboard is pinned to the API version that was current at the time of creation. This means that when Watenga releases a new API version with breaking changes, your existing integration continues working exactly as it does today — you opt in to new versions on your own schedule.

This is the same model used by Stripe. Your API version is attached to your API key, not to individual requests.

What Counts as a Breaking Change

Watenga considers the following to be breaking changes that require a new API version:

• Removing a field from a response — if you currently read transaction.cardLast4 and we removed that field, your code would break.
• Changing the type of a field — if feeAmount changed from a string to a number, strict type checks in your code would fail.
• Changing the meaning of a field — if status values changed from completed to succeeded, your if (status === 'completed') checks would stop working.
• Removing an endpoint — if we removed GET /v1/transactions/:id, any code calling it would break.

The following are not breaking changes and can happen at any time without a version bump:

• Adding a new field to a response — your code should ignore unknown fields.
• Adding a new endpoint — existing integrations are unaffected.
• Adding a new optional request parameter — omitting it still works.
• Fixing a bug — even if you were relying on the buggy behaviour, a security fix takes precedence.

Checking Your Current Version

Your API version is shown in the Developer Dashboard under each API app. It is also returned in the Watenga-Version response header on every API call:

curl -I https://api.watenga.africa/v1/account/balance \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

HTTP/2 200
content-type: application/json
watenga-version: 2026-01-01
...

Upgrading Your API Version

When a new API version is available, you can upgrade in the Developer Dashboard:

1. Go to https://dashboard.watenga.africa/developer
2. Open your API app
3. Under Overview, click Upgrade API version
4. Read the migration guide for the new version (linked from the changelog)
5. Test your integration in sandbox with a new sandbox app set to the new version
6. Once satisfied, upgrade your live app

Migration Guides

Watenga provides a minimum 6-month notice period before deprecating any API version. You will receive email notifications at 6 months, 3 months, and 1 month before a version is retired.