WordPress update_term_meta Example: Store Taxonomy Data Safely

Last reviewed: April 29, 2026

Taxonomy terms often need more than just a name and description. Category badge colors, landing-page intros, sponsor labels, and external IDs are all common examples of data that belongs to the term itself. update_term_meta() is the native way to store that data without inventing a custom table too early.

This guide shows how to update term metadata safely and read it back in templates or plugin logic.

Update a simple custom field on a term

<?php
$term_id = 42;
$color   = '#14532d';

$updated = update_term_meta( $term_id, 'vulnwp_badge_color', $color );

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

For small structured fields like color codes, labels, or external references, term meta is usually the right storage layer.

Sanitize before storing user-provided values

$label = isset( $_POST['vulnwp_term_label'] )
	? sanitize_text_field( wp_unslash( $_POST['vulnwp_term_label'] ) )
	: '';

update_term_meta( $term_id, 'vulnwp_term_label', $label );

Term meta is still content that may later be rendered in the admin UI, templates, feeds, or API responses. Sanitize on input and escape on output.

Read the value back when rendering term-driven UI

$badge_color = get_term_meta( $term_id, 'vulnwp_badge_color', true );

if ( $badge_color ) {
	printf(
		'<span class=\"term-badge\" style=\"--badge-color:%s\">%s</span>',
		esc_attr( $badge_color ),
		esc_html( single_term_title( '', false ) )
	);
}

When the value is retrieved for output, treat it like any other stored input. Escape it according to the output context.

Keep the meta keys stable and namespaced

Use a project-specific prefix such as vulnwp_ so later code is easier to search, audit, and migrate. Generic keys like color or label age badly in large installs.

Production checklist

• Store only term-owned data in term meta.
• Sanitize inputs before calling update_term_meta().
• Escape retrieved values at render time.
• Use stable, namespaced meta keys.
• Handle WP_Error when the update result needs validation.
• Document the expected shape of each key used by templates or APIs.

Common mistakes

• Using vague meta keys. Collisions and ambiguity increase over time.
• Skipping sanitization. Stored values often travel farther than expected.
• Putting large relational data into term meta. Not every data model belongs there.
• Assuming output is safe because it came from the database. Escape on render every time.
• Using term meta before the taxonomy model is stable. The key design should be deliberate.

Related reading

If the term itself may need to be created programmatically first, pair this with the wp_insert_term guide. If the workflow first checks whether the term exists, use the term_exists article.

References and further reading

• WordPress Code Reference: update_term_meta()
• WordPress Code Reference: get_term_meta()
• WordPress Code Reference: register_taxonomy()