Skip to content

Versioning & Deprecation

The PartnerHub API evolves in place: we add to it continuously, but we don't break integrations that already work. There is no /v1 versus /v2 to choose or migrate between — you always call the current API. This page is our backwards-compatibility contract: what may change without notice, what counts as a breaking change, and how we announce and phase out anything we retire.

Compatibility: what can change

We may make backwards-compatible changes at any time, without prior notice. Anything that would break an existing integration is a breaking change, and we only make those through the deprecation process below.

Backwards-compatible (non-breaking) — may ship at any time

  • New API endpoints and resources.
  • New optional fields in a response.
  • New optional request parameters, where leaving them out keeps the existing behaviour.
  • New possible values for a field — for example a new status. Build your integration to tolerate values it doesn't recognise yet.
  • Wording changes to human-readable messages (not the HTTP status code or the documented error shape).

Breaking — only through the deprecation process

  • Removing or renaming a field, endpoint, or resource.
  • Changing the type or format of an existing field.
  • Adding a new required request parameter, or making an existing optional one required.
  • Removing a value a field could return, or changing the meaning of an existing value.
  • Changing how you authenticate, or the HTTP status code returned for an existing outcome.

Build defensively. Ignore fields you don't use, and tolerate new fields and values you don't recognise. Integrations that do this are never affected by a backwards-compatible change.

How we announce deprecations

When we need to make a breaking change, we deprecate the old behaviour first and keep it working for a transition period. We announce it in two places:

  • Response headers on the affected endpoint, so your integration can detect a deprecation automatically — even if nobody read this page:
    • Deprecation: true — this endpoint, or a field it returns, is deprecated.
    • Sunset: <date> — the date (an HTTP-date, RFC 8594) after which the old behaviour may stop working.
    • Link: <url>; rel="successor-version" — where the replacement lives, when there is one.
    • X-Deprecated-Fields — the specific response fields being retired, when only fields (not the whole endpoint) are affected.
    • A Warning: 299 header, and sometimes a note in the response body, for a change you need to act on during the transition.
  • This documentation — the deprecation and its replacement are described on the relevant reference page.
Example: deprecation response headers 
HTTP/1.1 200 OK
Deprecation: true
Sunset: Thu, 01 Oct 2026 00:00:00 GMT
Link: </api/financing_cases>; rel="successor-version"

Minimum transition period

We keep a deprecated endpoint or field working for at least three months after we announce it — the date we commit to is always in the Sunset header, in the future. For larger changes, such as retiring a whole endpoint or field, the window is typically longer (around six months). We never remove something without a future Sunset date.

What to do: watch your responses for the Deprecation and Sunset headers — log them, or alert on them — and migrate to the documented replacement before the sunset date.

Current transitions

As of August 2026

Two changes are in their transition period right now. If your integration uses them, plan your migration before the dates below. Always treat the Sunset header on your own responses as the authoritative date.

Idempotency-Key becomes required on checkout — 2026-09-06
From 2026-09-06, POST /api/carts/{id}/checkout requires an Idempotency-Key header. Until then a request without one still succeeds but returns a Deprecation / Warning header. Send a unique key (a UUID v4) per checkout so retries are safe. See the Cart reference.
The /api/quotes endpoint is being retired — Sunset 2026-10-01
/api/quotes is superseded by /api/financing_cases (Sunset: 2026-10-01). The checkout response fields quoteId / quoteLink are likewise superseded by financeCaseId / financeCaseLink. Migrate to the Financing Case reference.

The API version

The API is versionless in its URLs. Every endpoint lives under /api — there is no /v1 or /v2 to pin to or migrate between. You always call the current API, and the compatibility contract above is what protects your integration.

The machine-readable API description at /api/docs.json does carry a version field. That is the release version of the PartnerHub platform — a calendar-based build tag such as 2026.06.22. It tells you which build you're talking to; it is not a contract version, and it does not change how you call the API.

The API handbook and this portal may also carry their own document version — that is the version of the documentation, separate again from the platform release. None of these numbers is something your code needs to send or match: rely on the compatibility contract and the Deprecation / Sunset headers instead.