Article

Move OpenAI prompt objects to code before November 30

For teams using saved OpenAI prompts, a migration checklist to preserve versions, variables and cache behavior before the November 30 shutdown.

Editorial illustration for Move OpenAI prompt objects to code before November 30: an arrow connects an old service to its replacement. Not documentary evidence.

Apps that depend on OpenAI’s saved prompt objects need to move their prompts into application code before November 30, 2026. OpenAI’s shutdown schedule covers reusable prompt objects—saved instructions and templates referenced by an app—and /v1/prompts.

Move the saved content into versioned application code, then send its messages and settings directly to the Responses API. The official migration guide describes that replacement; the practical work is preserving the version users receive, carrying over dynamic inputs and checking cache costs.

This is an approaching deadline, not a new announcement: OpenAI dates the notice to June 3, 2026. Its published schedule does not specify a shutdown time or timezone, so plan to finish before November 30.

Check whether your app uses saved prompt IDs

Review request-building code, wrapper libraries and deployment settings for prompt.id, identifiers beginning pmpt_ and /v1/prompts dependencies. The Responses API reference describes a prompt reference with an ID, an optional version and variables. Include scheduled jobs, queued requests and fallback routes in the review; a source-code search alone is not a complete inventory.

Apps already sending their own instructions and input without a saved-prompt dependency do not need this particular migration. For a business using a supplier-built AI app, the useful question is whether production requests use saved prompt IDs—and who owns removing them. This is not a notice that ordinary ChatGPT use or every OpenAI API request is ending.

Preserve the version and settings serving users

Before changing a request, make a reviewed record of each active prompt and its replacement. Capture:

  • The deployed prompt ID and version, its owner and the application feature that uses it. For calls without a pinned version, establish which content they currently receive; do not assume the latest edit is live.

  • The actual instructions, examples, message roles and variable mapping, including any image or file inputs.

  • The effective model and request configuration, including tools, output format, reasoning settings and caching options where used.

The prompt schema allows variables to be strings or typed text, image and file inputs. Copying visible text alone can therefore miss part of the request. Retrieve the material through your existing authorized access and keep private customer values out of repository fixtures. The migration guidance does not establish a general bulk-export procedure or post-shutdown recovery path.

Keep the current supported model and other settings stable for the initial move where feasible. The model shown in a documentation example is not a required upgrade. Track any model replacement separately; our OpenAI model-retirement checklist covers that different dependency.

Replace the prompt reference with direct inputs

OpenAI recommends named, code-managed prompt helpers with typed or validated arguments. For each saved prompt, make the following mapping:

  • prompt.id becomes a named helper containing the approved prompt content; prompt.version becomes a repository revision or release identifier your deployment can trace.

  • prompt.variables becomes validated helper arguments. Keep images and files as the appropriate input types rather than converting everything into strings.

  • The helper builds the messages passed through input. Supply the required model and applicable request settings directly, and remove the managed prompt reference.

Preserve the existing separation between instructions and user content: combining everything into one user message changes the request’s meaning. OpenAI’s text-generation guidance explains that developer instructions have priority over user messages.

Check follow-up turns too. If you place rules in the top-level instructions parameter, they apply only to that request; previous_response_id does not carry those instructions forward. Send the required rules again on later calls that need them.

If you use Codex to automate repository edits, review project trust for unattended Codex jobs before scheduling that work. Automation does not replace reviewing the preserved prompt content.

Check caching separately from the code change

Prompt caching reuses work for an unchanged beginning of a request, called its prefix. OpenAI’s cache documentation requires matching rendered context and an eligible cached boundary—not just similar-looking text. Message structure, tools and relevant settings can affect that match.

Keep stable instructions before per-request values. As a practical consequence of prefix matching, avoid adding a changing release timestamp ahead of otherwise reusable content; record release identity in deployment logs instead. Moving storage into code alone does not guarantee an unchanged bill.

Preserve working cache settings for the initial move. If introducing explicit cache breakpoints, check the model’s supported mode and minimum prefix length. Top-level instructions cannot hold an explicit breakpoint; the cache guide shows supported content blocks. A short example prompt is not proof of cache savings.

For applicable Responses models, compare usage.input_tokens_details.cached_tokens and cache_write_tokens, including write counts by lifetime, alongside total input and realized cost. The usage-accounting guidance distinguishes reads, writes and ordinary input; a cache-write rate is the total rate for those tokens, not an extra fee added to ordinary input.

What could change on the usage bill?

Illustrative arithmetic, not a measured migration result: for an app already using GPT-6 Astra, OpenAI’s Standard short-context rates on November 15 are $10 per million ordinary input tokens, $1 per million cached-input tokens and $12.50 per million 30-minute cache-write tokens.

Assume ten requests each contain a 2,000-token prefix, with eligible boundaries and matching settings. In the reuse case, assume one cold write followed by nine full reads within valid cache coverage:

  • One write plus nine reads: (2,000 × $12.50 + 9 × 2,000 × $1) ÷ 1,000,000 = $0.043.

  • Ten distinct prefixes, each written once: 10 × 2,000 × $12.50 ÷ 1,000,000 = $0.25.

  • The same token volume charged entirely as ordinary input: 10 × 2,000 × $10 ÷ 1,000,000 = $0.20.

These are assumed usage patterns, not a savings forecast or a reason to switch models. Only the selected prefix is costed; changing inputs after it, outputs, tools, other pricing tiers, taxes and engineering time are excluded. The comparison shows why repeated writes and successful reuse need separate checks.

Finish with a staged rollout and a usable rollback

OpenAI’s code-managed prompting guidance puts prompt changes through repository review and deployment controls. Keep domain experts involved in approving the wording, and retain an approved code-managed version to restore if a release fails. After the shutdown, switching back to the old prompt object is not a durable rollback.

Before directing all production traffic to the replacement, use sanitized cases covering ordinary requests, missing values, tools, structured output, image or file inputs and follow-up turns where applicable. Compare the rendered requests, required task behavior and usage costs. Model output can vary between runs, so byte-identical prose is not a universal pass condition.

Assign a cutover owner and date, then inspect deployed requests and queued work for remaining saved-prompt references. Keep Agent Builder and Evals transitions on separate lists if you use them: OpenAI lists them as distinct retirements. This migration is complete when the relevant application paths can run—and roll back—without the saved-prompt service.