wp_delete_term: delete a taxonomy term
Removes a term. There is no trash for terms and no undo.
Arguments
| Argument | Required | Meaning |
|---|---|---|
term_id |
Yes | The term to delete |
taxonomy |
Yes | Its taxonomy |
dry_run |
No | Report without deleting |
Permissions
Allow content writes open, and manage_categories.
What happens to the posts
The posts survive. Their classification does not: every post that carried the term loses it, silently and immediately.
Nothing about the posts is otherwise changed, and nothing warns you how many were affected. A term used by 200 posts and a term used by none are deleted the same way, with the same response.
That is why the post count is the number to look at before deleting anything.
Read the count first
wp_get_categories and wp_get_tags return a count per term.
| Count | What deletion means |
|---|---|
| 0 | Cleanup. Safe. |
| 1–2 | Probably an accident when the term was created. Check the posts. |
| Many | A structural change to how the site is organised. Stop and think. |
Show me the post count for term 42 before deleting anything.
Hierarchical taxonomies: check the children
Deleting a parent category affects its children. Because term listings report no hierarchy at all, the tools cannot show you whether a term has any.
Check the structure in the WordPress admin before deleting anything in a hierarchical taxonomy. This is a real gap and worth respecting.
The dry run is thin
dry_run returns the term ID it would delete — not the term, not its name, not its count.
So it confirms the argument was built correctly and nothing else. Pair it with a listing:
List the categories and show me term 42 with its count. Then use a dry run for the deletion.
Never delegate the criterion
Name IDs:
Delete terms 42 and 57. Nothing else.
Not "delete the unused tags". A tag with one post is not unused, and the assistant deciding which terms your site does not need is a judgement it cannot make — with an irreversible operation and no way to check its work afterwards.
This is the same reasoning as wp_delete_media, and it applies for the same reason: no undo, and no visibility of what depends on the thing being removed.
What is affected beyond the posts
| What breaks | Why |
|---|---|
| The term archive page | The URL 404s |
| Menu items pointing at that archive | Not removed automatically |
| Internal links to the archive | Not rewritten |
| Templates or feeds filtered by the term | Return nothing |
| Any saved filter or query using it | Silently empty |
Menu items are the one most often missed. See Edit a navigation menu.
What it returns
deleted, true or false. Not the record — read it first if you want it noted.
Alternatives
- Rename it if the problem is the name. Every post stays attached. See
wp_update_term. - Reassign the posts first, then delete the now-empty term, if the goal is to merge two terms.
- Leave it. An unused term costs nothing except a line in a list.
After deleting
- Check the posts that used the term still have sensible classification.
- Check for menu items and links pointing at the dead archive.
- Purge the cache — archive pages are exactly what a page cache holds.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_forbidden |
No manage_categories |
| Posts lost their category | Expected; deletion detaches the term |
| A menu item now 404s | Menu items are not cleaned up |
| The archive still loads | Cached |
Related
wp_update_term— renaming is usually betterwp_get_categories— read the count first- Recover from a failed write