Update a taxonomy term

wp_update_term changes only supplied fields on a term. Renaming preserves its slug unless you explicitly pass a new one. Existing post assignments remain attached to the term.

Arguments

Argument Meaning
taxonomy, term_id Required destination taxonomy and term
name Display name
slug Explicit replacement slug; may change the archive URL
description Description with permitted HTML
parent Parent in the same hierarchical taxonomy; zero makes a root term
thumbnail_id Editable image attachment on this site; zero clears it
background_image_id Editable background image attachment on this site; zero clears it
order Nonnegative native POM position; lower values appear first
expected_revision Revision from wp_get_term or a preview; required to apply
dry_run Validate and preview without changing the term
approval_id Single-use approval for the exact reviewed request

At least one editable field is required. Images and order require active POM Theme. Attachment IDs are resolved to the same image URLs used by the native term editor. Other terms are not renumbered when order changes.

Apply a change

  1. Read wp_get_term with the exact taxonomy and ID.
  2. Preview the supplied fields using dry_run: true and the current expected_revision.
  3. Inspect before, the proposed fields and pom values. If changing a slug or parent, account for public archive links.
  4. Submit the write and approve its review.
  5. Repeat the identical request with approval_id. Inspect complete, failed_fields and the returned term, then read it back.

The taxonomy's management capability and edit_term for that term are required, along with content-write scopes and the content write gate. A stale revision is refused. A metadata storage failure can leave a partial result; inspect the returned term rather than retrying blindly.

For a name-only cleanup, use wp_rename_terms from the taxonomy reference. It accepts no slug or image fields and can rename up to 50 terms under one approval. For multiple positions, use wp_reorder_terms.

Language and translation links are read for revision checks and preserved by these operations. They are not reassigned by a term update. Translations that already share a slug can be renamed independently while keeping that shared slug. An explicitly different slug still follows WordPress collision checks.

Update items in bulk
Previous
WordPress comment and metadata tool reference
Next