Change Freezes
A change freeze stops changes to what an environment serves for a stretch of time: a holiday sales weekend, a code freeze, an incident. While a window is active, anyone who tries to change a flag in a frozen environment is refused, from the dashboard, the Management API, the MCP server and anything else built on the API. An Owner or Admin can still break the freeze for a single change, and that change is audited.
Change freezes are on Business and Enterprise plans. Reading flags, evaluating them and SDK traffic are never affected. Your applications keep getting flag values the whole time.
What a freeze blocks
Section titled “What a freeze blocks”A freeze blocks writes that change what an environment serves for flags:
- turning a flag on or off
- targeting rules: creating, editing, deleting, reordering, or replacing them all at once
- prerequisites
- the flag’s environment configuration, such as its default variation and rollout
- copying a flag’s configuration into the frozen environment, as described in Compare and Copy Environments
- starting, resuming or advancing a rollout ramp
- deleting the environment, or deleting the project that holds it
What a freeze does not block
Section titled “What a freeze does not block”- editing a segment
- flag-wide edits: variations, name, description, tags, archiving, deleting or restoring a flag, owner and expiry, and client-side visibility
- creating or cancelling a scheduled change. The scheduled change still has to clear the freeze when it comes due
- configuring a flag trigger
- revoking an SDK key
- pausing or aborting a rollout ramp
- reading anything, evaluating flags, and SDK streaming
Segment edits and flag-wide edits aren’t scoped to one environment, and a freeze names environments, so it only gates writes that land in one. A segment edit can change what a frozen environment serves, so a freeze is not a guarantee that nothing there can move. Aborting a ramp is also allowed, and it can lower the rollout percentage the environment serves.
Creating a window
Section titled “Creating a window”Open Organization settings and find the Change freezes card. Freeze now and Schedule a freeze are in it. The project header also has Freeze now, and project settings show that project’s windows. A window has (the card’s dialogs also offer Hold them until the window ends or Fail them for scheduled changes):
- a name and a reason, which are shown to anyone the freeze blocks
- environments to cover. An organization-wide window matches environments by key, such as
production, in every project that has one. A project window covers environments of that project, and a window can cover all environments (allEnvironmentson the API) - a start and an end, in UTC
- a policy for scheduled changes, Hold or Fail (see below)
A window is half-open: it covers its start time and ends the instant its end time arrives. A window that starts at 00:00 and ends at 06:00 enforces up to, but not including, 06:00.
Freeze now
Section titled “Freeze now”Freeze now starts a window immediately. The window asks for a name, a reason and the environments, and the end time is optional. It can be open-ended, with no end time, and stays active until someone ends it. This is the incident button. Only a freeze-now window may leave the end open. A window you schedule for later needs an end time.
Editing, ending and deleting
Section titled “Editing, ending and deleting”Owners and Admins create, edit, end and delete windows. Other members can see them. A running window can be renamed, given a new reason, extended or shortened (to a future time), or have its environments or policy changed (below Business, only renaming, re-reasoning and shortening are allowed; see Plans and downgrades). Its start can’t move. Every edit is audited. End stops an active window now. Only a window that hasn’t started yet can be deleted. An ended window stays in the list as history.
What the refusal looks like
Section titled “What the refusal looks like”A blocked change gets HTTP 423 and the error code change_frozen on the Management API (CHANGE_FROZEN in the dashboard). The body carries a change_freeze object so a client can show when the freeze ends without parsing the message:
{ "error": "change_frozen", "message": "Environment 'production' is frozen by the change freeze 'Black Friday code freeze' until 2026-11-30 06:00 UTC. An Owner or Admin can break the freeze by sending an X-Intent-Reason and X-Freeze-Override: true.", "change_freeze": { "id": "6f1c1f0e-5d6e-4c58-9a3b-0d3a5a1d2e11", "name": "Black Friday code freeze", "environment_key": "production", "ends_at": "2026-11-30T06:00:00Z", "can_override": true }, "docs_url": "https://featureflip.io/docs/management-api/errors/change_frozen"}ends_at is null for an open-ended freeze. can_override says whether the caller’s role may break it. See change_frozen.
Breaking the freeze
Section titled “Breaking the freeze”An Owner or Admin can make one change inside a freeze, with a reason. This is break-glass.
- In the dashboard, a banner on a frozen flag environment says what is frozen and until when. Break the freeze… opens a dialog that asks why the change is needed and for you to tick I’m breaking the freeze on purpose. The override covers your next save only, and the controls lock again once it goes through. Cancel override disarms it.
- On the API, send both headers:
X-Intent-Reasonwith why you are doing it, andX-Freeze-Override: true. A reason alone does not break a freeze, so a routine change reason can’t do it by accident.
curl -X POST "https://api.featureflip.io/api/v1/orgs/acme/projects/checkout/flags/new-checkout/environments/production/toggle" \ -H "Authorization: Bearer $FEATUREFLIP_TOKEN" \ -H "Content-Type: application/json" \ -H "X-Intent-Reason: Reverting the 14:02 deploy, INC-412" \ -H "X-Freeze-Override: true" \ -d '{"enabled": false}'An override covers one request. A request that touches several environments, such as deleting a project, is covered by a single override. A member below Admin who sends the header is refused with change_frozen and can_override: false.
Every override is audited. The audit entry stores the reason, who broke the freeze and the window, and any webhook the change produces says so.
Scheduled changes inside a freeze
Section titled “Scheduled changes inside a freeze”A scheduled change that comes due while its environment is frozen never breaks the freeze by itself, even if an Admin scheduled it. What happens depends on the window’s policy:
- Hold (the default). The change stays Pending and applies once the freeze ends, oldest first, after a fresh check against any other window still in force.
- Fail. The change moves to Failed with a reason that names the freeze.
When windows overlap and one of them is Hold, Hold wins.
Pre-approving a scheduled change
Section titled “Pre-approving a scheduled change”Some changes have to land inside a freeze with nobody online, such as a launch at 00:00 on the first day of a sales weekend. An Owner or Admin can pre-approve one scheduled change through one specific window, with a reason. The approval is tied to that window. A window created later, such as an incident freeze, holds or fails the change unless you approve it for that window too.
Approvals are checked again when the change applies. The approver must still be an active Owner or Admin, and the window must still apply. If a check fails, the window’s Hold or Fail policy decides. You can revoke an approval while the change is still pending. After that, revoking returns 409.
The change then applies as a pre-approved change. Its audit entry is attributed to whoever scheduled it, with mode pre_approved, and carries the reason given when it was scheduled, or the approval’s reason if there was none. Granting the approval is its own audit entry, and the window’s list of approvals shows who approved each change. In the dashboard, a scheduled change inside a freeze shows a badge (Held by the window, Will fail: the window, or Pre-approved for the window), and Allow through on a held or failing change opens a dialog that asks for the reason.
Rollout ramps, triggers and copy
Section titled “Rollout ramps, triggers and copy”- Rollout ramps pause when a step falls due inside a freeze, and resume by themselves when it ends. If a person has also paused the ramp, it waits for them. Starting, resuming and advancing a ramp are blocked like any other change. Pausing and aborting are always allowed. See Rollout Ramps.
- Flag triggers fire during a freeze. A trigger is a kill switch, and a kill switch that a freeze could block would be no use during an incident. The change is recorded as a pass-through for the window.
- Copying configuration into a frozen environment is blocked. The copy preview warns
TARGET_FROZENbefore you try.
Audit log and webhooks
Section titled “Audit log and webhooks”A change made through a freeze carries the window on its audit entry: the entry names the window and says how the change got through. The modes are override (an Owner or Admin broke the freeze), pre_approved (a pre-approved scheduled change) and pass_through (a flag trigger). Creating, editing, ending and deleting a window, and granting or revoking an approval, are audited too.
Webhook payloads for a change made through a freeze carry a freeze member:
"freeze": { "id": "6f1c1f0e-5d6e-4c58-9a3b-0d3a5a1d2e11", "name": "Black Friday code freeze", "override": true, "preApproved": false, "passThrough": false }Windows send their own webhook events: change_freeze.created, change_freeze.updated and change_freeze.deleted, plus change_freeze.started and change_freeze.ended when a window’s time arrives or it is ended early. Each boundary event is sent once. A window that never started never sends a lone ended.
From the Management API
Section titled “From the Management API”Windows live under /api/v1/orgs/{org}/change-freezes:
| Method and path | What it does |
|---|---|
GET /change-freezes | List windows. Filter with status=Upcoming, Active or Ended |
GET /change-freezes/{id} | Get one window, with an ETag |
POST /change-freezes | Create a window |
PATCH /change-freezes/{id} | Edit a window. Send If-Match with the ETag |
POST /change-freezes/{id}/end | End an active window now |
DELETE /change-freezes/{id} | Delete a window that hasn’t started |
POST /change-freezes/{id}/approvals | Pre-approve a scheduled change through this window |
DELETE /change-freezes/{id}/approvals/{scheduledChangeId} | Revoke an approval |
Freeze every project’s production environment until a set time:
curl -X POST "https://api.featureflip.io/api/v1/orgs/acme/change-freezes" \ -H "Authorization: Bearer $FEATUREFLIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Black Friday code freeze", "reason": "No production changes during the sale", "environmentKeys": ["production"], "endsAt": "2026-11-30T06:00:00Z", "scheduledChangePolicy": "Hold" }'Leave out startsAt to start at once. Leave out endsAt as well for an open-ended freeze. A window with a startsAt needs an endsAt. Use "allEnvironments": true instead of environmentKeys to cover every environment. Add "project": "checkout" for a project window. The API reference has every field.
From MCP
Section titled “From MCP”list_change_freezes lists windows, or gets one with freeze_id, filtered by status and project. manage_change_freeze takes an action: create, freeze_now, update, end, delete, approve_scheduled_change and revoke_approval. Ask an agent to freeze production until Monday 06:00 UTC and it creates the window.
The flag-state write tools, such as toggle_flag, update_targeting and manage_targeting_rule, take freeze_override: true alongside reason to break a freeze, if the token belongs to an Owner or Admin. Without it, a frozen change comes back with an error that names the freeze and when it ends. See the MCP server.
Plans and downgrades
Section titled “Plans and downgrades”Creating a window and granting an approval need Business or Enterprise. Ending and deleting a window always work.
If your plan drops below Business:
- a window that was already active keeps enforcing until it ends
- a window that hadn’t started won’t start
- existing windows can only be renamed, given a new reason or shortened
Next steps
Section titled “Next steps”- Feature flags during a code freeze: planning a holiday freeze, from in-flight rollouts to the retro
- Critical Environments: require a written reason for every change
- Scheduled Changes: what happens to a change that comes due during a freeze
- Rollout Ramps: how ramps pause and resume around a freeze
- Audit Log: the record of every override and pass-through
- Webhooks: the
change_freeze.*events - Plans and limits: what each plan includes