API Versioning

ℹ️ Learn how to use the version header to control which API version your requests use

Billy tries to minimize the breaking changes on API platform. Sometimes, we have to. In this situation, the API platform uses a date-based versioning system that allows you to use and test upcoming changes before they become mandatory. This guide explains how to use the Billy-API-Version header to control which version of the API your requests use.

curl -H "Authorization: Bearer billy:o:org:key" \
  -H "Billy-API-Version: 2026-09-01" \
  https://platform.billyapp.live/v1/events

Why Date-Based Versioning?

Billy uses calendar dates to version API changes. This approach provides:

Predictability: You know exactly when changes take effect (e.g., "September 1st, 2026")
Early Testing: Test upcoming changes immediately
Smooth Transitions: Migrate at your own pace during the preview period
Single Stable Version: Only one stable version exists at any time, reducing complexity

💡 If you use a release version header (a future date) in your requests, you will seamlessly switch to the stable version once that date has passed.

Using the Version Header

Include the Billy-API-Version header in your API requests to specify which version you want to use.

Header Format

Billy-API-Version: <value>

Available Values

Value	Description
(none)	Uses the current stable version (default)
`stable`	Explicitly requests the stable version
`YYYY-MM-DD`	A published release date, e.g. `2026-09-01`. Before that date you get the upcoming version; after it, the same request keeps working and resolves to stable.

Response Header

The API echoes the last version of available API in Billy-API-Latest-Version response header:

Billy-API-Latest-Version: 2026-09-01

Best Practices

For migration in production

Use specific version. This ensures you automatically receive the new api format till the migration date, then it fallbacks on stable version after migration date.

curl -H "Authorization: Bearer billy:o:org:key" \
  -H "Billy-API-Version: 2026-09-01" \
  https://platform.billyapp.live/v1/events

For first development

Use the default behavior (no header) for production integrations. This ensures you automatically receive the current stable version:

curl -H "Authorization: Bearer billy:o:org:key" \
  https://platform.billyapp.live/v1/events

Benefits:

Simplest integration
Always uses stable, tested behavior
No code changes needed between releases

Examples

Basic Request (Default Behavior)

curl -H "Authorization: Bearer billy:o:your_org:your_key" \
  https://platform.billyapp.live/v1/events

Uses the current stable version automatically.

Explicit Stable Version

curl -H "Authorization: Bearer billy:o:your_org:your_key" \
  -H "Billy-API-Version: stable" \
  https://platform.billyapp.live/v1/events

Same as default, but explicit about using stable.

Specific Date Version

curl -H "Authorization: Bearer billy:o:your_org:your_key" \
  -H "Billy-API-Version: 2026-09-01" \
  https://platform.billyapp.live/v1/events

Uses the API version effective from September 1st, 2026. After September 1st, 2026, this becomes the stable version without any changes.

{
  "detail": "Invalid API version: YYYY-MM-DD"
}

How do I know which version I'm using?

Check the Billy-API-Version response header:

curl -I -H "Authorization: Bearer billy:o:org:key" \
  https://platform.billyapp.live/v1/events

# Response headers include:
# Billy-API-Version: 2026-09-01

What if I can't migrate before the release date?

Contact Billy support as soon as possible. While we cannot delay releases indefinitely, we may be able to provide guidance or temporary accommodations.

Resolution

Verify the date format is YYYY-MM-DD
Check that you're using one of the valid values: stable, or a date
Ensure there are no typos in the header name