TrackShip Docs
TrackShip Docs
Docs Tracking API API Reference Versioning & Deprecation Policy

Versioning & Deprecation Policy

This page describes how the TrackShip REST API is versioned and how any future changes to a version’s lifecycle will be communicated. It is intended to give developers — and automated agents integrating against our API — a stable, predictable contract they can rely on.

API Versioning

The TrackShip API uses URL path versioning. The version is included as a segment in the request path, immediately after the host:

https://api.trackship.com/v1/

The current and only active version is v1. All endpoints are accessible exclusively over HTTPS and require authentication — there are no unauthenticated or public endpoints. See Authentication for details on the required headers.

Backward Compatibility

Within a version, we treat the following as backward-compatible changes and may introduce them without incrementing the version number:

  • Adding new API endpoints.
  • Adding new optional request parameters to existing endpoints.
  • Adding new fields to existing response bodies.
  • Adding new values to existing enumerations (for example, new shipment statuses or new supported shipping providers).
  • Changing the order of fields in a response.

Integrations should be built to tolerate these additive changes — for example, by ignoring unknown response fields rather than failing on them. Changes that remove or rename fields, remove endpoints, or otherwise break existing behavior are considered breaking changes and would be introduced only under a new API version.

Deprecation Policy

There are currently no deprecated API versions or endpoints. The v1 API is fully supported.

If we ever need to deprecate an API version or an individual endpoint, we will follow the process below so that integrations are never broken without warning:

  1. Advance notice. We will announce the deprecation on this page and in the API Reference changelog at least 6 months before the affected version or endpoint is retired (the “sunset date”).
  2. Deprecation header. Responses from a deprecated endpoint will include a Deprecation HTTP header indicating that the endpoint is deprecated, per the IETF Deprecation header field specification.
  3. Sunset header. Responses from a deprecated endpoint will also include a Sunset HTTP header (RFC 8594) carrying the date after which the endpoint may stop responding.
  4. Migration path. When a replacement is available, we will document the migration path and, where practical, run the old and new surfaces in parallel throughout the deprecation window.

An example of the headers a deprecated endpoint would return:

Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://docs.trackship.com/docs/tracking-api/api-reference/>; rel="deprecation"

Because these signals are delivered as standard HTTP response headers, automated clients and agents can detect an upcoming change programmatically and migrate before the sunset date.