OpenAI GPT-5 and O3 Snapshot Deprecation Guide: December 2026 Migration Planning

On June 11, 2026, OpenAI announced the deprecation and removal of six first-generation GPT-5 and O3 model snapshots from the API. The shutdown date is December 11, 2026 — roughly 175 days from now. If your codebase pins any of these date-stamped model IDs, you need a migration plan. Not a reminder in your calendar for November — a plan you test and validate now, while there is still time to catch regressions.

This guide provides the exact replacement mapping, before/after code diffs, pricing delta analysis, rollback strategies, and a production checklist. We also cover how this fits into the broader 2026 deprecation landscape alongside Anthropic's deprecation cadence and Chinese provider sunsets.

We route OpenAI-compatible requests through configured providers and support provider/model routing and fallback where the live product path supports it. We do not claim universal model support, zero downtime, or guaranteed cheapest pricing. Every date and pricing figure below is sourced from OpenAI's official documentation at retrieval time.

30-second answer

• Deprecation announced: June 11, 2026 (OpenAI Deprecations, retrieved 2026-06-20).
• Shutdown date: December 11, 2026. After this date, API requests to these model IDs will return errors.
• Models affected: 6 snapshots — gpt-5-2025-08-07, gpt-5-mini-2025-08-07, gpt-5-nano-2025-08-07, gpt-5-pro-2025-10-06, o3-2025-04-16, and o3-pro-2025-06-10.
• Recommended replacements: GPT-5.5 family (gpt-5.5, gpt-5.4-mini, gpt-5.4-nano, gpt-5.5-pro).
• Notice period: 6 months — consistent with OpenAI's policy for generally available models.
• Action required now: Audit your codebase for pinned snapshot IDs. Start shadow-testing replacements. Do not wait until November.

Full model replacement matrix

The table below lists every affected model, its shutdown date, and OpenAI's recommended replacement. All data from the OpenAI Deprecations page, retrieved 2026-06-20.

Key pattern: The O3 reasoning models fold into the GPT-5.5 family. OpenAI has unified the reasoning and general-purpose lines — there is no separate "o-series" replacement.

Before/after code: updating model IDs

Python SDK (openai >= 1.x)

Before — pinned to deprecated snapshot:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-5-2025-08-07",  # ← deprecated, shuts down Dec 11
    messages=[
        {"role": "user", "content": "Explain routing fallback patterns"}
    ]
)

After — migrated to replacement:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-5.5",  # ← recommended replacement
    messages=[
        {"role": "user", "content": "Explain routing fallback patterns"}
    ]
)

O3 reasoning model migration

# Before — O3 snapshot
response = client.chat.completions.create(
    model="o3-2025-04-16",  # ← deprecated
    messages=[{"role": "user", "content": "Solve this step by step..."}]
)

# After — GPT-5.5 (unified reasoning + general-purpose)
response = client.chat.completions.create(
    model="gpt-5.5",  # ← replacement
    messages=[{"role": "user", "content": "Solve this step by step..."}]
)

Node.js / TypeScript

// Before
const response = await openai.chat.completions.create({
  model: "gpt-5-pro-2025-10-06",  // ← deprecated
  messages: [{ role: "user", content: "..." }],
});

// After
const response = await openai.chat.completions.create({
  model: "gpt-5.5-pro",  // ← replacement
  messages: [{ role: "user", content: "..." }],
});

cURL

# Before
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model": "o3-pro-2025-06-10", "messages": [...]}'

# After
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model": "gpt-5.5-pro", "messages": [...]}'

Pricing impact: old snapshots vs. replacements

Deprecated snapshot models are currently billed at their original rates. After migration, pricing shifts to the replacement tier. The table below compares current GPT-5.5 family pricing (OpenAI API Pricing, retrieved 2026-06-20).

Cost considerations:

• gpt-5 → gpt-5.5: The GPT-5.5 flagship is priced at $5/$30 (input/output). If you were on the original GPT-5 snapshot pricing, expect a modest increase reflecting improved capabilities.
• gpt-5-mini → gpt-5.4-mini: At $0.75/$4.50, the mini tier remains the most cost-efficient option for latency-sensitive workloads.
• o3 → gpt-5.5: The O3 reasoning snapshots migrate to GPT-5.5 at $5/$30. If you were paying O3 reasoning-tier premiums, this may represent a simplification — but verify with your actual usage patterns.
• gpt-5-pro / o3-pro → gpt-5.5-pro: The pro tier at $30/$180 is the premium reasoning option. Budget accordingly if you rely on extended reasoning.

Use prompt caching to reduce effective input costs — cached tokens are 90% cheaper on GPT-5.5.

Gotchas: behavior changes between snapshot versions

Replacing a pinned snapshot with a "latest" model introduces potential behavior drift. Watch for these:

1. Output style differences. GPT-5.5 may produce longer or shorter responses than gpt-5-2025-08-07 for the same prompt. Run your eval suite before switching production traffic.

2. Reasoning mode unification. The O3 series was purpose-built for chain-of-thought reasoning. GPT-5.5 absorbs this capability but may handle reasoning_effort parameters differently. Test your reasoning-heavy prompts explicitly.

3. Token counting changes. The GPT-5.5 tokenizer may differ slightly from the GPT-5 snapshot tokenizer. If you have strict token-budget logic, validate counts.

4. Rate limits. Rate limits are per-model-family. Migrating from a snapshot to the current model may place you into a different rate-limit tier. Check your organization's rate limits after switching.

5. Fine-tuned model dependency. If you fine-tuned on any of these base snapshots, your fine-tuned variants will also stop working. OpenAI's deprecation page notes that fine-tuned versions of deprecated models are removed on the same schedule.

Rollback path: pinning during the testing window

You have until December 11, 2026, to test. Use this window wisely:

1. Shadow routing. Send a percentage of traffic to the replacement model while continuing to serve from the deprecated snapshot. Compare outputs.

2. A/B evaluation. Run your eval suite against both models. Flag any quality regressions.

3. Staged rollout. If you pass evals, roll out to 10% → 50% → 100% over 2–4 weeks.

4. Pin to a specific GPT-5.5 snapshot once OpenAI publishes one (e.g., gpt-5.5-2026-XX-XX). This gives you behavioral stability while avoiding the deprecated model.

5. Fallback configuration. Configure a fallback chain: primary gpt-5.5 → fallback gpt-5.4 → fallback gpt-5.4-mini. If the replacement model has an outage or quality regression, traffic automatically reroutes.

Broader 2026 OpenAI deprecation landscape

The December 11 GPT-5/O3 shutdown is part of a larger deprecation wave. Here is the full timeline of OpenAI model retirements through the end of 2026:

Source: OpenAI Deprecations, retrieved 2026-06-20.

Key takeaway: If you are still on GPT-3.5 Turbo, GPT-4, or GPT-4 Turbo — those shut down October 23, 2026, before the GPT-5/O3 snapshots. Plan both migrations together.

Cross-provider deprecation context

OpenAI's December 2026 shutdown does not happen in isolation. Teams running multi-provider stacks face concurrent deprecation waves:

• Anthropic: Claude models follow a roughly 60-day deprecation cadence after notice. See our Anthropic deprecation migration guide.
• Chinese providers (DashScope, Volcengine, Zhipu): Multiple sunset waves hitting July–September 2026. See our Chinese AI model deprecation calendar.
• Azure OpenAI (Microsoft Foundry): Azure retirements track the same OpenAI model IDs but may have different shutdown dates. Check the Azure model retirement schedule for your deployment region.

TheRouter integration: routing and fallback for OpenAI model transitions

TheRouter routes OpenAI-compatible requests through configured providers and supports provider/model routing and fallback where the live product path supports it. For teams managing this migration:

• Model ID aliasing. Configure your routing layer to map deprecated model IDs to their replacements. When the deprecated snapshot shuts down, traffic automatically routes to the replacement without client-side code changes.
• Fallback chains. Set up gpt-5.5 → gpt-5.4 → gpt-5.4-mini as a fallback chain. If the primary model is unavailable or over rate limits, requests degrade gracefully. See our LLM API fallback routing guide.
• Unified billing. Track costs across model transitions through unified billing and accounting surfaces where implemented, so you can compare pre- and post-migration spend.

For a complete walkthrough of migrating from direct OpenAI SDK calls to a routing layer, see our OpenAI to TheRouter migration guide.

1. Swap three values, not three SDKs. Change api_key, base_url, and model in the existing OpenAI client. Keep your request/response code unchanged.
2. Map model IDs explicitly. The target provider's model id is almost never identical to the OpenAI id. Keep a single dict of { openai_id: target_id } outside business logic.
3. Verify streaming format. SSE chunks must follow the OpenAI data: {...} + data: [DONE] contract. Test one streaming call before moving production traffic.
4. Check rate-limit headers. Some providers omit x-ratelimit-* headers. Add a wrapper that defaults safely when headers are absent.
5. Keep a rollback path. Ship the swap behind a feature flag, run both endpoints in shadow for 24 hours, then cut over.

Production checklist

Use this checklist before your migration deadline:

• Audit pinned model IDs. Search your codebase for gpt-5-2025, gpt-5-mini-2025, gpt-5-nano-2025, gpt-5-pro-2025, o3-2025, o3-pro-2025. Also check environment variables, config files, and infrastructure-as-code templates.
• Check fine-tuned models. If you fine-tuned on any deprecated base model, those fine-tuned variants shut down on the same date.
• Run eval suite. Compare replacement model outputs against your current baseline. Flag regressions in quality, latency, or token usage.
• Test prompt caching. GPT-5.5 supports prompt caching at $0.50/1M cached tokens (90% discount). Implement it to offset any cost increase.
• Verify rate limits. Check your organization's rate limits for the replacement model tier.
• Set up fallback. Configure a fallback chain so your app degrades gracefully if the replacement model has issues.
• Schedule staged rollout. Plan a 10% → 50% → 100% rollout at least 30 days before December 11.
• Monitor post-migration. Track error rates, latency p95, and user satisfaction for 2 weeks after full rollout.
• Remove deprecated model references. After successful migration, clean up dead code referencing deprecated model IDs.
• Set a calendar reminder. October 23, 2026 — GPT-3.5/GPT-4/O4-mini shut down. If you also use those, plan both migrations together.

FAQ

Q: Can I keep using the deprecated snapshots after December 11, 2026? A: No. After the shutdown date, API requests to these model IDs will return errors. OpenAI does offer dedicated capacity options for extended access in some cases — contact their sales team if you have a hard dependency.

Q: Will GPT-5.5 behave identically to gpt-5-2025-08-07? A: No. GPT-5.5 is a newer model with improved capabilities. Expect differences in output quality, style, and token usage. Always test before migrating production traffic.

Q: What about Azure OpenAI deployments? A: Azure model retirements generally track OpenAI's schedule but may have different dates. Check the Azure model retirement page for your specific deployment.

Q: I'm using O3 for reasoning tasks. Does GPT-5.5 support the same reasoning features? A: GPT-5.5 absorbs O3's reasoning capabilities. The reasoning_effort parameter and chain-of-thought behavior are supported, but may differ in implementation. Test your reasoning-heavy workloads explicitly.

Q: What if I find a quality regression after migrating? A: Roll back to the deprecated snapshot (it's still available until December 11), file a regression report with OpenAI, and investigate whether prompt adjustments or a different replacement model (e.g., gpt-5.4 instead of gpt-5.5) resolves the issue.

---

All deprecation dates and pricing from OpenAI Deprecations and OpenAI API Pricing, retrieved 2026-06-20. Model capabilities and behavior may change. Cross-check against official documentation before making production decisions.