wp_delete_page: delete a page
Trashes a page, or removes it permanently. Identical to wp_delete_post, and the write with the widest consequences in this chapter.
Arguments
| Argument | Required | Meaning |
|---|---|---|
id |
Yes | The page to delete |
force |
No | Permanently delete instead of trashing |
dry_run |
No | Report without deleting |
Permissions
Allow content writes open, and delete_post on that specific page.
Consider unpublishing instead
Almost every request that sounds like "delete this page" is better served by setting it to draft:
Set page 88 to draft.
That removes it from the site, keeps the content, keeps the URL reserved, and is reversible in one step. Deletion is none of those things.
Reach for deletion only when the page must genuinely cease to exist.
Mechanics
force, dry_run, trash-versus-permanent and the recovery position all behave exactly as described in wp_delete_post. Default to trashing.
The rest of this page is about what makes deleting a page different.
Deleting a page breaks more than a post
A page is usually referenced from several places, and none of them are updated by the deletion:
| What breaks | Why |
|---|---|
| Menu items | A menu entry pointing at a deleted page |
| Internal links | Links in other pages' content |
| Child pages | Their parent no longer exists |
| Campaign and external links | Anything outside the site |
| Search results | Until search engines re-crawl |
Check all of these before deleting. The child-page case is the one most often missed: deleting a parent leaves children with a broken hierarchy and, depending on the theme, changed URLs.
Confirm the link, not just the title
The dry run returns the record including its link:
Use a dry run and show me the page you would delete, including its title and link.
For a page, the link is the more useful confirmation of the two. Titles repeat across a site — several pages can be called "Services" — while the URL path is unique and shows where the page sits in the hierarchy.
Before deleting
- [ ] Read the page and confirm the title.
- [ ] Search for internal links to it — see
wp_search. - [ ] Check the navigation menus.
- [ ] Check whether it has child pages.
- [ ] Decide whether a redirect is needed for the URL.
- [ ] Confirm unpublishing would not do instead.
After deleting
- Check the site for broken links and orphaned menu items.
- Set up a redirect if the URL had traffic.
- Purge the cache — a cached copy of a deleted page can still be served.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_post_not_found |
Wrong ID |
pom_ai_mcp_forbidden |
No delete_post on that page |
| Gone permanently | force was passed |
| Menu shows a dead entry | Menu items are not removed automatically |
| Child pages misbehave | Their parent was deleted |
| The page still loads | Cached |
Related
wp_update_page— unpublishing is usually betterwp_delete_post- Edit a navigation menu