Deprecation notices buyers can plan around

Three facts on one page

A deprecation notice buyers can plan around gives three things together: the date the model stops answering, the model that replaces it with its exact version, and a note on what changes when they switch. Spread across a blog post, a changelog and an email, the same facts are found late, and a team that finds a retirement date late treats it as an outage.

Buyers also read the policy before any model is retired. How much notice you give, and whether you have kept to it, is part of what they are buying when they choose a provider for something that must run next year.

The notice also has to reach the right person. The engineer who integrated the model may have left; the account owner may be in finance. A notice sent only to the signup address may reach nobody who acts on it, so let buyers name a contact for retirements.

What a team does with a retirement date

They work backwards from it. Someone has to run the replacement against their own evaluation set, compare outputs, adjust prompts that relied on the old behaviour, and check that the cost per request has not moved. In a regulated business someone also has to sign the change off. Each step takes calendar time that the notice period has to cover.

So the date matters less than the gap between the notice and the date. A long notice with a firm date is planned around. A short one, or a date given only as a quarter, gives the buyer a reason to look at providers that give longer.

A team using several models may prefer to batch its migrations and move once when retirements fall in the same season. A notice that lists every retirement in the next year lets them do that; a notice for one model at a time makes them move repeatedly.

Give the date in a form a calendar accepts, with the time zone, and do not move it once given unless you move it later rather than earlier.

What the migration note should say

The note is short and specific. It lists the request parameters that changed or were removed, any difference in how the replacement formats its output, whether tool calling or structured output behaves differently, and whether the tokeniser changed, since a new tokeniser changes how many tokens the same text costs.

That last point catches buyers who compare only rates. A replacement at the same per-token price that counts the same prompt as more tokens is dearer per request. A buyer will find this in testing; a note that says it first saves them the surprise and saves you the ticket.

Where you know of prompts that behaved one way on the old model and another on the new one, give an example. Buyers learn more from one before-and-after pair than from a paragraph saying behaviour may differ.

Name the replacement exactly

Saying a model will be replaced by the latest version of its family leaves the buyer to guess which model, which version and which price. Name it the way it appears in the API, give its context window and both token rates, and say whether those differ from the retiring model.

If the replacement costs more, say so on the notice. Buyers compare it on the token price table anyway, against other sellers of the same model and against other models, and they will find the difference. Finding it on your page first reads better than finding it on someone else's.

If there is no replacement, say that plainly too. A buyer can plan around a gap that is stated. They cannot plan around a sentence promising something similar soon.

Aliases that move

Some providers offer a short alias that always points at the newest version, alongside pinned names that do not change. Both are useful. The trouble comes when a buyer does not know which kind they are calling, and outputs shift on a day nobody announced.

State on the model page which names are pinned and which move, and give the date an alias last moved. A changelog entry when it moves costs one line. This site keeps a changes page on the same principle: a value that moved should say when.

Give buyers notice before an alias moves, not only after. A short warning lets a team pin the old version while they test the new one, which is often all a team needs.

Where the notice should live

One page lists every model with a retirement date, newest dates first, each with the replacement and a link to the migration note. The pricing page links to it beside every model that is scheduled to go. Emails and dashboard banners point back to that page rather than repeating its contents in different words.

When a retired model leaves your pricing page, the last rate read for it ages out, because a rate older than 21 days is hidden rather than shown stale. A claimed vendor can correct a listing sooner than that, which is useful when a retirement is brought forward.

Keep retired models on the list after their date, marked as retired, with the replacement. Someone auditing an old system looks there to find what a model was moved to and when.