Docs / guides/ versioning

title: API Versioning

description: Understand how Wontopos handles API versioning, deprecation, and migration.

API Versioning

Wontopos uses URL-based versioning. The current stable version is v1.

Version header

Specify the API version in the URL path:

curl https://api.wontopos.com/v1/marketplace/apis 
  -H "Authorization: Bearer $WONTOPOS_API_KEY"

You can also pin a specific minor version using the Wontopos-Version header:

curl https://api.wontopos.com/v1/marketplace/apis 
  -H "Authorization: Bearer $WONTOPOS_API_KEY" 
  -H "Wontopos-Version: 2026-03-01"

Supported versions

VersionStatusEnd of life
v1 (2026-03-01)Stable—
v1 (2026-01-01)Stable2026-12-31
v0 (beta)Deprecated2026-06-30

v0 deprecation

The v0 beta API will be removed on June 30, 2026. Migrate to v1 before that date.

Deprecation policy

  • 6-month notice before removing any endpoint or version
  • Deprecation warnings appear in the Deprecation response header
  • Email notifications sent to all affected API key owners
  • Migration guides published for all breaking changes

Breaking vs. non-breaking changes

Breaking changes (require a new version):

  • Removing an endpoint or field
  • Changing a field type
  • Changing required parameters
  • Changing authentication requirements

Non-breaking changes (additive, deployed to current version):

  • Adding new optional fields
  • Adding new endpoints
  • Adding new enum values
  • Adding new optional query parameters

Migration guide

Review the changelog

Check the [changelog](/docs/changelog) for a list of changes between versions.

Update your version header

Set the `Wontopos-Version` header to the new version date.

Test in sandbox

Verify your integration works against the sandbox environment.

Deploy to production

Update your production configuration once tests pass.