Ability: acf/create-custom-taxonomy

Documentation Ability: acf/create-custom-taxonomy

Last updated Mar 30, 2026

Overview

Creates a new custom taxonomy in ACF.

Description

Creates a new taxonomy using ACF’s taxonomy registration system. The taxonomy is registered with WordPress and optionally enabled for AI access.

Input

{
  "taxonomy": "product_category",
  "label": "Product Category",
  "plural_label": "Product Categories",
  "post_types": ["product"]
}

Required Properties

taxonomy (string) The taxonomy key/slug. Must be lowercase alphanumeric with underscores or hyphens. Maximum 32 characters.

label (string) The singular label for the taxonomy.

plural_label (string) The plural label for the taxonomy.

post_types (array) Array of post type slugs to associate with this taxonomy.

Optional Properties

description (string) Description of the taxonomy.

public (boolean) Whether the taxonomy is publicly accessible. Default: true

hierarchical (boolean) Whether the taxonomy supports parent/child relationships (like categories). Default: false (flat like tags)

show_in_rest (boolean) Whether to expose in the REST API. Required for block editor and AI abilities. Default: true

rest_base (string) Custom REST API base path. Defaults to taxonomy key.

show_admin_column (boolean) Whether to show a column in the post list table. Default: false

allow_ai_access (boolean) Whether to allow AI access to this taxonomy. Default: true

ai_description (string) Description to help AI understand the purpose of this taxonomy.

Output

{
  "success": true,
  "taxonomy": {
    "taxonomy": "product_category",
    "label": "Product Category",
    "plural_label": "Product Categories",
    "hierarchical": false,
    "public": true,
    "post_types": ["product"],
    "show_in_rest": true,
    "allow_ai_access": true
  },
  "message": "Custom taxonomy 'product_category' created successfully."
}

Annotations

Annotation	Value
readonly	false
destructive	false
idempotent	false

Permissions

Requires the ACF capability (default: manage_options).

Example

Create a hierarchical Event Category taxonomy:

{
  "taxonomy": "event_category",
  "label": "Event Category",
  "plural_label": "Event Categories",
  "description": "Categories for organizing events",
  "post_types": ["event"],
  "hierarchical": true,
  "show_admin_column": true,
  "allow_ai_access": true,
  "ai_description": "Hierarchical categories for event types (conferences, workshops, meetups)"
}

Response:

{
  "success": true,
  "taxonomy": {
    "taxonomy": "event_category",
    "label": "Event Category",
    "plural_label": "Event Categories",
    "description": "Categories for organizing events",
    "hierarchical": true,
    "public": true,
    "post_types": ["event"],
    "show_in_rest": true,
    "show_admin_column": true,
    "allow_ai_access": true,
    "ai_description": "Hierarchical categories for event types (conferences, workshops, meetups)"
  },
  "message": "Custom taxonomy 'event_category' created successfully."
}

Errors

Error	Cause
Invalid taxonomy key	Key contains invalid characters or exceeds 32 characters
Taxonomy already exists	A taxonomy with this key is already registered
Missing required field	taxonomy, label, plural_label, or post_types not provided
Invalid post type	One or more specified post types do not exist

Notes

• Taxonomy keys must be unique across WordPress
• Reserved taxonomy keys (category, post_tag, etc.) cannot be used
• The taxonomy is immediately registered and available in the admin
• Dynamic abilities (query, create, view, update, delete) are registered for taxonomies with show_in_rest and allow_ai_access enabled
• Set hierarchical: true for category-like taxonomies with parent/child support
• Set hierarchical: false for tag-like flat taxonomies

Related

• Integrations: Ability: acf/custom-taxonomies
• Integrations: Ability: acf/custom-post-types
• Integrations: Ability: acf/create-custom-post-type
• Videos: Creating a Custom Taxonomy with ACF
• Integrations: Ability: acf/create-field-group