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

---

# wp_set_post_terms( int $post_id, string|array $terms = '', string $taxonomy = 'post_tag', bool $append = false ): array|false|󠀁[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)󠁿

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#description)
    - [See also](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#see-also)
 * [Parameters](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#user-contributed-notes)

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

Sets the terms for a post.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#description)󠁿

### 󠀁[See also](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#see-also)󠁿

 * [wp_set_object_terms()](https://developer.wordpress.org/reference/functions/wp_set_object_terms/)

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

 `$post_id`intoptional

The Post ID. Does not default to the ID of the global $post.

`$terms`string|arrayoptional

An array of terms to set for the post, or a string of terms separated by commas.
Hierarchical taxonomies must always pass IDs rather than names so that children 
with the same names but different parents aren’t confused.

Default:`''`

`$taxonomy`stringoptional

Taxonomy name. Default `'post_tag'`.

Default:`'post_tag'`

`$append`booloptional

If true, don’t delete existing terms, just add on. If false, replace the terms with
the new terms.

Default:`false`

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

 array|false|[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
Array of term taxonomy IDs of affected terms. [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
or false on failure.

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

    ```php
    function wp_set_post_terms( $post_id = 0, $terms = '', $taxonomy = 'post_tag', $append = false ) {
    	$post_id = (int) $post_id;

    	if ( ! $post_id ) {
    		return false;
    	}

    	if ( empty( $terms ) ) {
    		$terms = array();
    	}

    	if ( ! is_array( $terms ) ) {
    		$comma = _x( ',', 'tag delimiter' );
    		if ( ',' !== $comma ) {
    			$terms = str_replace( $comma, ',', $terms );
    		}
    		$terms = explode( ',', trim( $terms, " \n\t\r\0\x0B," ) );
    	}

    	/*
    	 * Hierarchical taxonomies must always pass IDs rather than names so that
    	 * children with the same names but different parents aren't confused.
    	 */
    	if ( is_taxonomy_hierarchical( $taxonomy ) ) {
    		$terms = array_unique( array_map( 'intval', $terms ) );
    	}

    	return wp_set_object_terms( $post_id, $terms, $taxonomy, $append );
    }
    ```

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

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

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

Creates term and taxonomy relationships.

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

Determines whether the taxonomy object is hierarchical.

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

Retrieves translated string with gettext context.

  |

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

| Used by | Description | 
| [wp_set_unique_slug_on_create_template_part()](https://developer.wordpress.org/reference/functions/wp_set_unique_slug_on_create_template_part/)`wp-includes/theme-templates.php` |

Sets a custom slug when creating auto-draft template parts.

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

Publishes a post by transitioning the post status.

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

Sets the tags for a post.

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

Sets categories for a post.

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

Inserts or updates a post in the database.

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

Assign a format to a post

  |

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

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

| Version | Description | 
| [2.8.0](https://developer.wordpress.org/reference/since/2.8.0/) | Introduced. |

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

 1.   [Skip to note 4 content](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#comment-content-1117)
 2.    [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/wp_set_post_terms/#comment-1117)
 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_set_post_terms%2F%23comment-1117)
     Vote results for this note: 21[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_set_post_terms%2F%23comment-1117)
 4.  **Non hierarchical term example**
 5.  For non-hierarchical terms (such as tags), you can pass either the term name or
     id. If you pass the id there is only one caveat: You must pass it as an integer,
     and it must be in an array. This is necessary because any non-array value passed
     will be converted to a string, which will be interpreted as a term name.
 6.      ```php
         $tag = '5'; // Wrong. This will add the tag with the *name* '5'.
         $tag = 5; // Wrong. This will also add the tag with the name '5'.
         $tag = array( '5' ); // Wrong. Again, this will be interpreted as a term name rather than an id.
     
         $tag = array( 5 ); // Correct. This will add the tag with the id 5.
         wp_set_post_terms( $post_id, $tag, $taxonomy );
         ```
     
 7.  This function will only work on the native post type. For a taxonomy on a custom
     post type use [wp_set_object_terms()](https://developer.wordpress.org/reference/functions/wp_set_object_terms/)
 8.   [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_set_post_terms%2F%3Freplytocom%3D1117%23feedback-editor-1117)
 9.   [Skip to note 5 content](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#comment-content-5250)
 10.   [stalkerxxl](https://profiles.wordpress.org/stalkerxxl/)  [  5 years ago  ](https://developer.wordpress.org/reference/functions/wp_set_post_terms/#comment-5250)
 11. [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_set_post_terms%2F%23comment-5250)
     Vote results for this note: 2[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_set_post_terms%2F%23comment-5250)
 12. I do not know why, but you need to wrap your term_id in Array ((int) $ Term_id)–
     Then it will work as id … otherwise it is to create a term with name = $ Term_id
 13.     ```php
         $exchange = term_exists( $this->response['exchangeShortName'], 'exchange' );
     
         if ( ! $exchange ) {
             $exchange = wp_insert_term( $this->response['exchange'], 'exchange', array( 'slug' => $this->response['exchangeShortName'] ) );
         }
     
         // create new term with name = $exchange['term_id'] - BUG?
         wp_set_post_terms( $this->postID, array( $exchange['term_id'] ), 'exchange', false ); 
     
         // It works fine, does not create a new term, and simply attaches the existing ID
         wp_set_post_terms( $this->postID, array( (int) $exchange['term_id'] ), 'exchange', false );
         ```
     
 14.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_set_post_terms%2F%3Freplytocom%3D5250%23feedback-editor-5250)
 15.  [Skip to note 6 content](https://developer.wordpress.org/reference/functions/wp_set_post_terms/?output_format=md#comment-content-1116)
 16.   [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/wp_set_post_terms/#comment-1116)
 17. [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_set_post_terms%2F%23comment-1116)
     Vote results for this note: -1[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_set_post_terms%2F%23comment-1116)
 18. **Hierarchical term example**
 19. For hierarchical terms (such as categories), you must always pass the id rather
     than the term name to avoid confusion where there may be another child with the
     same name.
 20. To get the term id you can use:
 21.     ```php
         $term_id = term_exists( $term, $taxonomy, $parent );
         ```
     
 22. You may also need to pass by reference:
 23.     ```php
         wp_set_post_terms( $post_id, $term, &$taxonomy );
         ```
     
 24.  * Should the last line be: `wp_set_post_terms( $post_id, $term_id, $taxonomy );`
        To show you are passing the term ID from line above. Also term_exists will 
        return an array so you need to specify the ID as specified in [term_exists examples](https://developer.wordpress.org/reference/functions/wp_insert_term/#comment-572).
        And the ampersand seems like a typo.
      * [Norm](https://profiles.wordpress.org/casualmagic/) [7 years ago](https://developer.wordpress.org/reference/functions/wp_set_post_terms/#comment-3735)
 25.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_set_post_terms%2F%3Freplytocom%3D1116%23feedback-editor-1116)

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