API Versioning

How It Works

The WhaleTools API uses date-based version identifiers in the format vYYYY-MM-DD. Each version represents a snapshot of the API contract on that date. Your requests are pinned to a specific version, so breaking changes in newer versions will never affect your integration.

If you do not specify a version, requests default to the latest stable version.

Setting the Version

Pass the X-API-Version header with your desired version on every request.

curl https://vm.whaletools.cloud/v1/stores/{storeId}/products \
  -H "x-api-key: wk_live_your_key_here" \
  -H "X-API-Version: v2026-03-07"

Or set it globally in your client library:

const response = await fetch(
  'https://vm.whaletools.cloud/v1/stores/{storeId}/products',
  {
    headers: {
      'x-api-key': 'wk_live_your_key_here',
      'X-API-Version': 'v2026-03-07',
    },
  }
);

const data = await response.json();

Version in Responses

Every API response includes headers indicating which version was used and whether a newer version is available.

HTTP/1.1 200 OK
X-API-Version: v2026-03-07
X-API-Latest-Version: v2026-03-07
Content-Type: application/json

When X-API-Version differs from X-API-Latest-Version, consider upgrading to access the newest features.

What Counts as a Breaking Change

A new version is created when a change would break existing integrations. The following are considered breaking changes:

• •Removing or renaming an existing field from a response
• •Changing the type of an existing response field
• •Adding a new required parameter to a request
• •Changing error response formats or status codes
• •Removing an endpoint entirely

The following are not breaking changes and may happen without a new version: adding new optional fields to responses, adding new endpoints, adding new optional query parameters, or adding new event types.

Deprecation Policy

When a new API version is released, the previous version enters a 6-month deprecation window. During this period:

• •Months 1-3: The deprecated version works normally. API responses include a Sunset header with the retirement date.
• •Months 4-6: The deprecated version continues to work but responses include a Deprecation-Warning header.
• •After 6 months: The deprecated version is retired and requests using it will return 410 Gone.

All deprecations are announced in the changelog and via email to affected API key owners.

Version History