wp_update_page: update a page
Updates a page. Identical to wp_update_post, and the tool most likely to change something a visitor sees within seconds.
Arguments
| Argument | Required | Meaning |
|---|---|---|
id |
Yes | The page to update |
title |
No | New title |
content |
No | New body |
excerpt |
No | New excerpt |
slug |
No | New slug |
status |
No | New status |
dry_run |
No | Report without writing |
Permissions
Allow content writes open, and edit_post on that specific page.
Mechanics
Field handling, the dry run and the status rules are exactly as in wp_update_post: only the fields you pass are changed, and an omitted status leaves the page as it is.
The rest of this page is about what makes updating a page different.
Why pages deserve more care than posts
Three reasons, and they compound:
Pages are almost always published. A post might be a draft; a service page is live.
Pages are structural. They appear in navigation, in sitemaps and in search results, and other pages link to them.
Pages are often builder content. The content field holds a shortcode structure, and replacing it wholesale destroys the layout — the single most expensive mistake available in this chapter.
Read the page before writing
Not optional for builder content:
Read page 88 and show me its structure. Change only the hero section. Preserve every other section, its shortcodes and its parameters exactly.
An assistant that has not read the structure cannot preserve it. The published prompt update_pom_builder_page_preserving_structure exists for exactly this job and is more reliable than describing the constraint yourself. See Prompt recipes.
Changing the slug changes a public URL
A title change alone does not move the page. Passing slug does, and that breaks inbound links, bookmarks, campaign URLs and search results.
If a page is nested, changing a parent's slug moves every child's URL too.
Plan redirects before the write, not after someone reports a 404.
Unpublishing
To take a page off the site without deleting it:
Set page 88 to draft.
That is almost always the right answer to "remove this page" — it is reversible, keeps the content, and avoids the broken links a deletion leaves. See wp_delete_page.
After writing
- Read the page back.
- Open it on the front end, at desktop and mobile width.
- Check the navigation still shows what you expect.
- Purge the cache.
Step 2 matters for builder pages specifically: a stored record can be correct and the rendered layout still wrong.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_forbidden |
No edit_post on that page |
| The layout broke | Builder content replaced rather than edited |
| The URL changed | slug was passed |
| Child pages moved | A parent slug changed |
| The site shows the old version | Cache not purged |
Related
wp_get_page— always call this firstwp_update_post- Update a page safely