Title: wp_insert_category
Published: April 25, 2014
Last modified: August 20, 2026

---

# wp_insert_category( array $catarr, bool $wp_error = false ): int|󠀁[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)󠁿

## In this article

 * [Parameters](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#return)
 * [More Information](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#more-information)
 * [Source](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#wp--skip-link--target)

Updates an existing Category or creates a new Category.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#parameters)󠁿

 `$catarr`arrayrequired

Array of arguments for inserting a new category.

 * `cat_ID` int
 * Category ID. A non-zero value updates an existing category.
    Default 0.
 * `taxonomy` string
 * Taxonomy slug. Default `'category'`.
 * `cat_name` string
 * Category name. Default empty.
 * `category_description` string
 * Category description. Default empty.
 * `category_nicename` string
 * Category nice (display) name. Default empty.
 * `category_parent` int|string
 * Category parent ID. Default empty.

`$wp_error`booloptional

Default:`false`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#return)󠁿

 int|[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/) The
ID number of the new or updated Category on success. Zero or a [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
on failure, depending on param `$wp_error`.

## 󠀁[More Information](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#more-information)󠁿

Not all possible members of the $catarr array are listed here.

The value of category_nicename will set the slug. (In WordPress terminology, a “
nice” name is one that is sanitized for use in places like URLs. It is not meant
for displaying to humans, as you might assume.)

See [wp_create_category()](https://codex.wordpress.org/Function_Reference/wp_create_category)
for a simpler version which takes just a string instead of an array

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#source)󠁿

    ```php
    function wp_insert_category( $catarr, $wp_error = false ) {
    	$cat_defaults = array(
    		'cat_ID'               => 0,
    		'taxonomy'             => 'category',
    		'cat_name'             => '',
    		'category_description' => '',
    		'category_nicename'    => '',
    		'category_parent'      => '',
    	);
    	$catarr       = wp_parse_args( $catarr, $cat_defaults );

    	if ( '' === trim( $catarr['cat_name'] ) ) {
    		if ( ! $wp_error ) {
    			return 0;
    		} else {
    			return new WP_Error( 'cat_name', __( 'You did not enter a category name.' ) );
    		}
    	}

    	$catarr['cat_ID'] = (int) $catarr['cat_ID'];

    	// Are we updating or creating?
    	$update = ! empty( $catarr['cat_ID'] );

    	$name        = $catarr['cat_name'];
    	$description = $catarr['category_description'];
    	$slug        = $catarr['category_nicename'];
    	$parent      = (int) $catarr['category_parent'];
    	if ( $parent < 0 ) {
    		$parent = 0;
    	}

    	if ( empty( $parent )
    		|| ! term_exists( $parent, $catarr['taxonomy'] )
    		|| ( $catarr['cat_ID'] && term_is_ancestor_of( $catarr['cat_ID'], $parent, $catarr['taxonomy'] ) ) ) {
    		$parent = 0;
    	}

    	$args = compact( 'name', 'slug', 'parent', 'description' );

    	if ( $update ) {
    		$catarr['cat_ID'] = wp_update_term( $catarr['cat_ID'], $catarr['taxonomy'], $args );
    	} else {
    		$catarr['cat_ID'] = wp_insert_term( $catarr['cat_name'], $catarr['taxonomy'], $args );
    	}

    	if ( is_wp_error( $catarr['cat_ID'] ) ) {
    		if ( $wp_error ) {
    			return $catarr['cat_ID'];
    		} else {
    			return 0;
    		}
    	}
    	return $catarr['cat_ID']['term_id'];
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-admin/includes/taxonomy.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-admin/includes/taxonomy.php#L121)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-admin/includes/taxonomy.php#L121-L175)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#related)󠁿

| Uses | Description | 
| [wp_update_term()](https://developer.wordpress.org/reference/functions/wp_update_term/)`wp-includes/taxonomy.php` |

Updates term based on arguments provided.

  | 
| [wp_insert_term()](https://developer.wordpress.org/reference/functions/wp_insert_term/)`wp-includes/taxonomy.php` |

Adds a new term to the database.

  | 
| [term_exists()](https://developer.wordpress.org/reference/functions/term_exists/)`wp-includes/taxonomy.php` |

Determines whether a taxonomy term exists.

  | 
| [term_is_ancestor_of()](https://developer.wordpress.org/reference/functions/term_is_ancestor_of/)`wp-includes/taxonomy.php` |

Checks if a term is an ancestor of another term.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [wp_parse_args()](https://developer.wordpress.org/reference/functions/wp_parse_args/)`wp-includes/functions.php` |

Merges user defined arguments into defaults array.

  | 
| [is_wp_error()](https://developer.wordpress.org/reference/functions/is_wp_error/)`wp-includes/load.php` |

Checks whether the given variable is a WordPress Error.

  | 
| [WP_Error::__construct()](https://developer.wordpress.org/reference/classes/wp_error/__construct/)`wp-includes/class-wp-error.php` |

Initializes the error.

  |

[Show 4 more](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#)

| Used by | Description | 
| [wp_create_category()](https://developer.wordpress.org/reference/functions/wp_create_category/)`wp-admin/includes/taxonomy.php` |

Adds a new category to the database if it does not already exist.

  | 
| [wp_update_category()](https://developer.wordpress.org/reference/functions/wp_update_category/)`wp-admin/includes/taxonomy.php` |

Aliases [wp_insert_category()](https://developer.wordpress.org/reference/functions/wp_insert_category/) with minimal args.

  | 
| [wp_xmlrpc_server::wp_newCategory()](https://developer.wordpress.org/reference/classes/wp_xmlrpc_server/wp_newcategory/)`wp-includes/class-wp-xmlrpc-server.php` |

Creates a new category.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#changelog)󠁿

| Version | Description | 
| [3.0.0](https://developer.wordpress.org/reference/since/3.0.0/) | The `'taxonomy'` argument was added. | 
| [2.5.0](https://developer.wordpress.org/reference/since/2.5.0/) | $wp_error parameter was added. | 
| [2.0.0](https://developer.wordpress.org/reference/since/2.0.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#user-contributed-notes)󠁿

 1.  [Skip to note 2 content](https://developer.wordpress.org/reference/functions/wp_insert_category/?output_format=md#comment-content-774)
 2.   [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/wp_insert_category/#comment-774)
 3. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_insert_category%2F%23comment-774)
    Vote results for this note: 3[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_insert_category%2F%23comment-774)
 4. To insert a new category:
 5.     ```php
        //Define the category
        $wpdocs_cat = array('cat_name' => 'Wpdocs Category', 'category_description' => 'A Cool Category', 'category_nicename' => 'category-slug', 'category_parent' => '');
    
        // Create the category
        $wpdocs_cat_id = wp_insert_category($wpdocs_cat);
        ```
    
 6.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_insert_category%2F%3Freplytocom%3D774%23feedback-editor-774)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_insert_category%2F)
before being able to contribute a note or feedback.