WPResidence registers its custom post types and default property taxonomies through the WPResidence Core plugin (for example: wpresidence-core/post-types/property.php). For that reason, any custom taxonomy you add should be placed in a child theme (or a small custom plugin), not in the parent theme files.

1) Add the code in your child theme

Add the snippet below to:

• Appearance → Theme File Editor → (your child theme) functions.php, or
• via FTP in your child theme’s functions.php

<?php
/**
 * Register a custom taxonomy for WPResidence.
 * Tested with WPResidence 5.4.1+
 */

add_action( 'init', 'wpresidence_register_property_custom_taxonomy', 30 );

if ( ! function_exists( 'wpresidence_register_property_custom_taxonomy' ) ) {

	function wpresidence_register_property_custom_taxonomy() {

		$labels = array(
			'name'              => esc_html__( 'Custom Categories', 'wpresidence-core' ),
			'singular_name'     => esc_html__( 'Custom Category', 'wpresidence-core' ),
			'search_items'      => esc_html__( 'Search Custom Categories', 'wpresidence-core' ),
			'all_items'         => esc_html__( 'All Custom Categories', 'wpresidence-core' ),
			'parent_item'       => esc_html__( 'Parent Custom Category', 'wpresidence-core' ),
			'parent_item_colon' => esc_html__( 'Parent Custom Category:', 'wpresidence-core' ),
			'edit_item'         => esc_html__( 'Edit Custom Category', 'wpresidence-core' ),
			'update_item'       => esc_html__( 'Update Custom Category', 'wpresidence-core' ),
			'add_new_item'      => esc_html__( 'Add New Custom Category', 'wpresidence-core' ),
			'new_item_name'     => esc_html__( 'New Custom Category Name', 'wpresidence-core' ),
			'menu_name'         => esc_html__( 'Custom Categories', 'wpresidence-core' ),
		);

		register_taxonomy(
			'property_custom_category',         // 1) Taxonomy name (must be unique)
			array( 'estate_property' ),         // 2) Attach to WPResidence post type
			array(
				'labels'            => $labels,
				'hierarchical'      => true,
				'public'            => true,
				'show_ui'           => true,
				'show_admin_column' => true,
				'query_var'         => true,
				'show_in_rest'      => true, // Gutenberg/REST support
				'rewrite'           => array(
					'slug'         => 'custom_category',
					'with_front'   => false,
					'hierarchical' => true,
				),
			)
		);
	}
}

Notes:

• estate_property is the WPResidence Property custom post type.
• If you want to attach the taxonomy to other WPResidence content types, replace the object type array with one of the following:
  • Properties: estate_property
  • Agents: estate_agent
  • Agencies: estate_agency
  • Developers: estate_developer

(WordPress taxonomy registration reference)

2) Flush permalinks (important)

After adding the code, go to Settings → Permalinks and click Save Changes once. This flushes rewrite rules so your new taxonomy URLs work.

3) Add taxonomy terms

After that, you’ll be able to add terms for your new taxonomy from the WordPress admin (it will appear in the relevant admin menus once registered).

Important limitation (theme-specific)

Registering the taxonomy makes it available in WordPress (admin + URLs). If you also want that taxonomy to appear inside WPResidence-specific UI like advanced search builders, custom list filters, or special theme modules, additional theme integration is usually required (because those areas use internal field lists).