wp_create_term: create a taxonomy term

Creates a category, tag or custom taxonomy term.

Arguments

Permissions

Allow content writes open, and the manage_categories capability — which governs all taxonomies, not only categories.

Read the existing terms first

The failure this tool produces is not a broken write; it is a taxonomy that slowly fills with near-duplicates.

An assistant that cannot find "Maintenance" creates it, and now the site has "Maintenance" and "maintenance services" doing the same job with two archive pages.

List the existing terms first. Only create a term if nothing close exists, and tell me the name before you do.

That instruction costs one read call and prevents the most common taxonomy problem there is.

parent only means something for hierarchical taxonomies

Categories nest; tags do not. Check with wp_get_taxonomies before passing parent.

Two mistakes follow from not checking:

• Passing parent on a flat taxonomy — meaningless, and quietly ignored.
• Omitting parent on a hierarchical one — the term is created at the top level. It looks correct in a list and wrong in the site's navigation and URLs.

The second is the one that goes unnoticed, because a term list shows no hierarchy at all.

The slug becomes a public URL

Omitting slug derives it from the name. The slug is the term's archive URL, so it is public and it is awkward to change later — changing it breaks any link to that archive.

Set it deliberately when the derived form would be poor, and check what was created.

What it returns

The created term's identifiers, or an error if the taxonomy is invalid or the term already exists.

A duplicate name in a flat taxonomy is refused by WordPress. In a hierarchical one, the same name under a different parent is allowed — which is correct, and another reason to be deliberate about parent.

The dry run shows the payload, not the name

dry_run returns the slug, description and parent it would use. Note that the term name is not part of that payload, so the dry run confirms the supporting fields rather than the term itself.

Read it to check the parent and slug, which are the two fields most often wrong.

Creating terms as a side effect

Assigning a term needs its ID, so an assistant asked to tag posts will often create terms on the way. Decide in advance whether that is allowed, and say so:

You may not create terms. Use only the IDs I give you.

Or:

List the terms you intend to create and wait for approval.

See Create terms and organize content.

After creating

• Check the term appears where you expect in the WordPress admin, including under the right parent.
• Check the archive URL.
• Assign it to posts as a separate step with wp_add_post_terms, remembering that tool replaces by default.

Common problems

Related

• wp_get_categories — read before creating
• wp_update_term
• wp_add_post_terms