How to Register and Query Custom Taxonomies in WordPress Using Register_taxonomy() with REST API and Wp_query Integration

Learning how to register and query custom taxonomies in WordPress using register_taxonomy() with REST API and WP_Query integration is one of the most practical skills you can add to your WordPress development toolkit. Custom taxonomies let you organize content beyond the default categories and tags. They give your site structure, flexibility, and better content relationships. Whether you’re building a recipe site, a real estate listing platform, or a knowledge base, custom taxonomies make content management cleaner and more scalable. In this tutorial, you’ll create a custom taxonomy from scratch, expose it through the REST API, and query it using WP_Query. By the end, you’ll have a working implementation you can drop into any theme or plugin.

Prerequisites and Requirements for Custom Taxonomy Registration

Before you start working with custom taxonomy registration and querying, make sure you have the following in place.

Required setup:

  • A working WordPress installation (version 5.0 or higher)
  • Admin access to your WordPress dashboard
  • Access to your theme’s functions.php file or a custom plugin file
  • A code editor such as VS Code or Nano
  • Basic PHP knowledge
  • Optional: A REST API testing tool like Postman

Assumed knowledge: You should understand how WordPress hooks work. You should also know what a post type is. Familiarity with PHP arrays and functions will help.

Estimated time: 30–45 minutes.

You’ll be editing PHP files directly. Always back up your site before making changes. If you’re working on a live server, use a staging environment first. A simple mistake in functions.php can take your site down. Use a child theme or a custom plugin file to keep your changes safe and upgrade-proof.

How to Register Custom Taxonomies in WordPress Using register_taxonomy()

You might also find this useful: How to Install and Configure Fail2ban on Ubuntu Server for Ssh Protection

This section walks you through creating a custom taxonomy and attaching it to a post type.

Step 1: Open your functions.php or plugin file

Navigate to your theme directory on the server. If you’re using SSH, run:

nano /var/www/html/wp-content/themes/your-theme/functions.php

If you prefer, create a custom plugin file instead:

nano /var/www/html/wp-content/plugins/my-taxonomies/my-taxonomies.php

Add the plugin header to the top of a new plugin file:

<?php
/
  Plugin Name: My Custom Taxonomies
  Description: Registers custom taxonomies for the site.
  Version: 1.0
 /

Step 2: Register the custom taxonomy

Add the following code to register a taxonomy called “genre” for the default “post” post type. The register_taxonomy() function accepts three main arguments: the taxonomy name, the post type it attaches to, and an array of arguments.

function akensai_register_genre_taxonomy() {
    $labels = array(
        'name'              => 'Genres',
        'singular_name'     => 'Genre',
        'search_items'      => 'Search Genres',
        'all_items'         => 'All Genres',
        'edit_item'         => 'Edit Genre',
        'update_item'       => 'Update Genre',
        'add_new_item'      => 'Add New Genre',
        'new_item_name'     => 'New Genre Name',
        'menu_name'         => 'Genre',
    );

    $args = array(
        'labels'            => $labels,
        'hierarchical'      => true,
        'public'            => true,
        'show_ui'           => true,
        'show_in_rest'      => true,
        'rest_base'         => 'genres',
        'show_admin_column' => true,
        'rewrite'           => array( 'slug' => 'genre' ),
    );

    register_taxonomy( 'genre', array( 'post' ), $args );
}
add_action( 'init', 'akensai_register_genre_taxonomy' );

The key argument here is 'show_in_rest' => true. This exposes your taxonomy through the WordPress REST API automatically. The 'rest_base' argument sets the endpoint slug.

Step 3: Save the file and flush rewrite rules

After saving, go to your WordPress dashboard. Navigate to Settings → Permalinks and click Save Changes. This flushes rewrite rules without writing code. You should now see “Genre” in your Posts menu on the left sidebar.

Querying Custom Taxonomies with WP_Query and the REST API

Now that your taxonomy is registered, you need to pull posts from it. You can do this two ways: with WP_Query in PHP templates, or through the REST API endpoint.

Step 4: Query posts by taxonomy using WP_Query

Use the tax_query parameter inside WP_Query to filter posts by your custom taxonomy. Add this to a template file or shortcode:

$args = array(
    'post_type'  => 'post',
    'tax_query'  => array(
        array(
            'taxonomy' => 'genre',
            'field'    => 'slug',
            'terms'    => 'action',
        ),
    ),
);

$query = new WP_Query( $args );

if ( $query->have_posts() ) {
    while ( $query->have_posts() ) {
        $query->the_post();
        echo '

' . get_the_title() . '

'; } wp_reset_postdata(); } else { echo 'No posts found.'; }

This queries all posts tagged with the “action” genre slug. The wp_reset_postdata() call at the end is important. It restores the global $post variable after your custom query.

Step 5: Query the REST API endpoint

Because you set 'show_in_rest' => true, your taxonomy is available via the REST API. Test the endpoint using curl from your terminal:

curl -X GET "https://yoursite.com/wp-json/wp/v2/genres" 
  -H "Content-Type: application/json"

This returns a JSON list of all genre terms. To get posts filtered by a genre term ID, use:

curl -X GET "https://yoursite.com/wp-json/wp/v2/posts?genre=5" 
  -H "Content-Type: application/json"

Replace 5 with the actual term ID from your genres endpoint. You can find term IDs in the first curl response. For full details on REST API taxonomy parameters, check the WordPress REST API Handbook.

Step 6: Add terms programmatically

You can add terms to your taxonomy without using the dashboard. Use wp_insert_term() inside a function:

wp_insert_term( 'Action', 'genre', array(
    'slug' => 'action',
) );

wp_insert_term( 'Drama', 'genre', array(
    'slug' => 'drama',
) );

Run this once, then remove it. Leaving it in will attempt to insert duplicates on every page load.

Step 7: Assign a term to a post programmatically

Use wp_set_object_terms() to assign a genre to a specific post:

wp_set_object_terms( 42, 'action', 'genre' );

Replace 42 with your actual post ID. This is useful in import scripts or bulk operations. For a deeper look at taxonomy functions, the official register_taxonomy() documentation covers every available argument in detail.

Troubleshooting Common Issues with Custom Taxonomy Queries

Even with clean code, things go wrong. Here are the most common problems and how to fix them.

Taxonomy not showing in the dashboard: Check that 'show_ui' => true is set. Also confirm your add_action hook fires on init, not too late in the load order.

REST API endpoint returns 404: Make sure 'show_in_rest' => true is in your args. Then flush permalinks again from Settings → Permalinks. If the issue persists, deactivate other plugins to rule out conflicts.

WP_Query returns no results: Double-check the taxonomy slug and term slug. They’re case-sensitive. Use get_terms( 'genre' ) to print all available terms and verify the slugs match what you’re passing to tax_query.

Rewrite rules not working: If your taxonomy archive page shows a 404, the rewrite slug may conflict with an existing page. Change the 'slug' value in the 'rewrite' argument to something unique.

Duplicate term warnings: If you’re inserting terms programmatically, wrap the call in a check: if ( ! term_exists( 'action', 'genre' )

Similar Posts