OpenAI Deprecation Lifecycle Guide: Notice Periods, Shutdown Calendar, Migration Checklist

OpenAI does not retire models at random: an explicit lifecycle governs the process -- a deprecation announcement, a published shutdown date, promised minimum notice periods, and recommended replacements for every batch. This article unpacks the official Deprecations page: the difference between three key concepts, the official notice floors, real case timelines to calibrate your intuition, and a migration checklist your team can adopt as-is. All rules and dates are quoted from the official deprecations page and changelog (verified 2026-09-01).

1. Three Concepts: deprecation, shut down, legacy

The official deprecations page draws clear lines between the three terms:

• deprecation: the moment OpenAI announces a model or endpoint is entering retirement, it immediately becomes deprecated. Every deprecated object necessarily carries a shutdown date.
• shut down / sunset: OpenAI states these terms are used interchangeably -- both mean the model or endpoint is no longer accessible. From the shutdown date on, calls fail.
• legacy: models and endpoints that no longer receive updates. OpenAI uses the tag to signal where the platform is moving -- legacy objects will likely be deprecated at some point, but still work today.

The engineering takeaway: treat legacy as your cue to schedule a migration, treat deprecated as a countdown to a hard date, and treat shut down as too late. Chat Completions (the messages field) currently sits in the legacy stage -- the official guidance is to use the Responses API for new projects.

2. Notice Periods: the Official Floors

OpenAI sets minimum notice periods per model type (unless safety or compliance concerns require a faster timeline):

Three companion rules matter just as much:

1. Safety and compliance come first: if safety or compliance requires faster retirement, the notice periods above do not apply; OpenAI provides as much notice as reasonably possible.
2. Preview is not a production tier: OpenAI explicitly recommends against preview models for business-critical production workloads -- unless you can migrate on short notice.
3. Conditional life after shutdown: in some cases you can contact sales to provision dedicated capacity for continued access after the shutdown date. This is a commercial path, not a self-serve switch.

How notice reaches you: customers actively using a model are notified by email, the deprecation is documented on the page, and larger changes also come with blog posts.

3. Calibrating Your Instincts with Real Cases

The rules are floors -- where do real batches land? Four cases that have completed (or are completing) the cycle:

Two observations: first, actual execution hugs the floor -- 6 months means 6 months and 3 months means 3 months; do not count on "the average being generous". Second, the 3-month specialized-variant tier is real and enforced; teams building production integrations on aliases like chat-latest should pay particular attention.

4. The Current Shutdown Calendar (2026-09 to 2027-02)

Sorting every unexpired batch on the official deprecations page by date (verified 2026-09-01), the hard dates for the next six months:

This calendar keeps changing; the authoritative source is always the official deprecations page. Our weekly briefings track the additions and removals -- see the latest one, OpenAI Ecosystem Week 43 Briefing (2026-09-01): mTLS GA, Sora 2 Countdown, Shutdown Calendar.

5. The Five-Step Migration Checklist

Step one, inventory call sites. Turn the batch's model names from the deprecations page into a list and search your code and configuration globally:

#!/usr/bin/env bash
# Put this batch's model names from the deprecations page in models.txt (one per line)
# and search every code and configuration directory
for m in $(cat models.txt); do
  grep -rn --exclude-dir=node_modules --exclude-dir=.git "$m" \
    ~/projects ~/infra 2>/dev/null
done

Step two, map official replacements. Build a mapping table from each row's Recommended replacement and consolidate it into a single configuration layer instead of hardcoded strings everywhere:

# model_map.py -- central model alias management; a deprecation migration touches one file
MODEL_ALIASES = {
    # 2026-12-11 shutdown batch (official replacement suggestions)
    "gpt-5-2025-08-07": "gpt-5.6-sol",
    "gpt-5-mini-2025-08-07": "gpt-5.6-terra",
    "gpt-5-nano-2025-08-07": "gpt-5.6-luna",
    "o3-2025-04-16": "gpt-5.6-sol",
}

def resolve(model: str) -> str:
    return MODEL_ALIASES.get(model, model)

Step three, canary the swap. Switch a non-critical path to the replacement first and watch quality, latency, and cost. The call itself uses the Responses API's input field -- the model name is just one parameter:

from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model=resolve("o3-2025-04-16"),  # resolves to gpt-5.6-sol
    input="Summarize the payment terms in this contract",
)
print(resp.output_text)

Step four, regression compare. Run a fixed test set against both versions, focusing on structured output formats, tool-calling behavior, and edge cases -- a replacement model from a different generation may need prompt adjustments.

Step five, observe leftover traffic. Watch the Usage dashboard by model and API key for one to two weeks (the dashboard and the Usage API have supported the API-key dimension since 2026-08-04), confirm old-model traffic reaches zero, then set the shutdown date as a calendar backstop.

6. Common Mistakes and Troubleshooting

• Treating legacy as safe: legacy only means updates have stopped -- a deprecation announcement can arrive any time. Chat Completions sitting in legacy is the cautionary tale; new projects should start on the Responses API.
• Running production on preview models: preview notice can be as short as ~2 weeks; OpenAI itself recommends against it. Production belongs on GA models, or behind a two-week migration plan.
• Searching code but not infrastructure: model names hide in Terraform, Helm values, CI scripts, and colleagues' notebooks. Run the inventory command from section 5 over your whole infrastructure tree.
• Ignoring batches with an empty replacement column: no official replacement (such as the Sora 2 batch) does not mean no migration is needed -- it means the migration plan is your responsibility.
• Applying ChatGPT product-side retirement to the API: the product side retires models about 90 days after a successor ships; that calendar is not synchronized with API deprecations. Keep the two calendars separate.

7. Next Steps

• The official rules verbatim: OpenAI Deprecations (the source for every rule and date in this article).
• The timeline view of 2026 H2 updates: OpenAI 2026 H2 Model and API Release Timeline.
• Choosing between Responses API and Chat Completions: Responses API vs Chat Completions: Is It Time to Migrate?.
• Selection logic for replacement mapping: The complete guide to GPT models (2026-07): GPT-5.6 Sol, Terra, Luna.