WordPress wp_insert_term Example: Create Taxonomy Terms Safely

Last reviewed: April 28, 2026

Programmatically creating taxonomy terms is a routine requirement for importers, onboarding flows, theme setup, and plugin configuration. The risky part is assuming term creation always succeeds or that duplicate names will quietly resolve themselves.

This guide shows how to use wp_insert_term() to create taxonomy terms safely, with a stable slug and proper error handling.

Create a term with explicit arguments

<?php
$result = wp_insert_term(
	'Security Notes',
	'category',
	array(
		'slug'        => 'security-notes',
		'description' => 'Editorial posts focused on defensive WordPress implementation.',
	)
);

if ( is_wp_error( $result ) ) {
	return $result;
}

$term_id = (int) $result['term_id'];

The returned value is not a plain integer. WordPress returns an array with both term_id and term_taxonomy_id, so code should read the result intentionally.

Set a stable slug during automated setup

In migrations or plugin onboarding flows, a stable slug is usually better than relying on automatic slug generation from a display label. That keeps later term lookups deterministic across environments.

Handle duplicate and invalid-term failures cleanly

if ( is_wp_error( $result ) ) {
	if ( 'term_exists' === $result->get_error_code() ) {
		$term_id = (int) $result->get_error_data();
	} else {
		return $result;
	}
}

That branch is useful in idempotent setup routines where the term may already exist and the operation should remain safe to run twice.

Use the right taxonomy every time

Before inserting a term, be certain the taxonomy is already registered in the current request. If the taxonomy is loaded conditionally or too late, the insert will fail for the wrong reason.

Production checklist

• Pass the correct taxonomy slug explicitly.
• Set a stable slug for repeatable environments and imports.
• Handle WP_Error and the term_exists case deliberately.
• Read term_id from the returned array instead of assuming a scalar result.
• Ensure the taxonomy is registered before insert logic runs.
• Keep automated setup routines idempotent.

Common mistakes

• Treating the return value like a plain integer. The function returns a structured array on success.
• Ignoring WP_Error. Duplicate or invalid-term failures then surface later in worse places.
• Relying on generated slugs during migrations. Cross-environment naming drifts more easily.
• Running before the taxonomy exists. Registration order matters.
• Creating setup code that is not safe to rerun. Production jobs often execute more than once.

Related reading

If the code should first confirm whether a term already exists, pair this with the term_exists guide. If the created term is later attached to a post, continue with the wp_set_object_terms article.

References and further reading

• WordPress Code Reference: wp_insert_term()
• WordPress Code Reference: register_taxonomy()
• WordPress Code Reference: is_wp_error()