Skip to main content

List Categories

Retrieves all categories from WordPress including their metadata, hierarchy, and post counts.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Client Id - The client ID from the Connect node (optional if using direct credentials).

Options​

  • Site URL - (Optional) WordPress site URL. Use this if you want to authenticate directly without a Connect node.
  • Credentials - (Optional) WordPress username and application password. Use this if you want to authenticate directly without a Connect node.

Output​

  • Category List - An array of all category objects from WordPress.

How It Works​

The List Categories node retrieves all categories from WordPress using the WordPress REST API.

When executed, the node:

  1. Retrieves the authentication (either from Client Id or direct credentials)
  2. Sends a GET request to /wp-json/wp/v2/categories/ endpoint
  3. Returns an array of all category objects with their complete metadata

Category Object Structure​

Each category in the returned Category List contains:

  • id - Unique category ID
  • count - Number of posts in this category
  • description - Category description
  • link - Public URL to the category archive
  • name - Category display name
  • slug - URL-friendly category identifier
  • taxonomy - Always "category" for categories
  • parent - Parent category ID (0 for top-level categories)
  • meta - Custom meta fields

Authentication Methods​

Connect → Store Client Id → List Categories (use Client Id)

Method 2: Direct Credentials​

Provide both Site URL and Credentials directly in the node options.

Requirements​

  • A WordPress site with REST API enabled (WordPress 4.7+)
  • No special permissions required - categories are publicly accessible

Error Handling​

The node will return specific errors in the following cases:

  • Authentication failure (if using credentials)
  • Network connection errors
  • WordPress REST API disabled
  • Invalid response format

Usage Notes​

  • Returns all categories, including those with 0 posts
  • Categories are publicly accessible - no authentication required for basic retrieval
  • The result includes the complete category hierarchy information
  • Empty categories (count: 0) are included in the results
  • The default "Uncategorized" category is included
  • Results are sorted by name by default

Example Output​

Category List:

[
  {
    "id": 1,
    "count": 15,
    "description": "Posts that don't fit other categories",
    "link": "https://yoursite.com/category/uncategorized/",
    "name": "Uncategorized",
    "slug": "uncategorized",
    "parent": 0
  },
  {
    "id": 5,
    "count": 23,
    "description": "Posts about technology and software",
    "link": "https://yoursite.com/category/technology/",
    "name": "Technology",
    "slug": "technology",
    "parent": 0
  },
  {
    "id": 12,
    "count": 8,
    "description": "Web development articles",
    "link": "https://yoursite.com/category/technology/web-dev/",
    "name": "Web Development",
    "slug": "web-dev",
    "parent": 5
  }
]

Common Use Cases​

Category Management​

  • Audit existing category structure
  • Export category data
  • Verify category hierarchy
  • Check category usage (post counts)

Content Organization​

  • Analyze which categories are most used
  • Identify empty or unused categories
  • Map category relationships
  • Review category descriptions for SEO

Category Lookup​

  • Get category IDs for creating/updating posts
  • Find parent category IDs for creating subcategories
  • Verify category exists before assignment
  • Check category slugs for URL building

Data Migration​

  • Export categories from WordPress
  • Backup category structure
  • Sync categories between sites
  • Prepare category mapping for imports

Automation Setup​

  • Retrieve category IDs for automated workflows
  • Validate category assignments
  • Build dynamic category selection lists
  • Check category availability before creating posts

Filtering and Processing Results​

After retrieving the category list, you can process it using JavaScript or Filter nodes:

Find Category by Name​

const categories = msg.category_list;
const techCategory = categories.find(cat => cat.name === "Technology");
return { category_id: techCategory.id };

Get Top-Level Categories​

const categories = msg.category_list;
const topLevel = categories.filter(cat => cat.parent === 0);
return { top_level_categories: topLevel };

Get Categories with Posts​

const categories = msg.category_list;
const activeCategories = categories.filter(cat => cat.count > 0);
return { active_categories: activeCategories };

Build Category Hierarchy​

const categories = msg.category_list;

function buildHierarchy(parentId) {
  return categories
    .filter(cat => cat.parent === parentId)
    .map(cat => ({
      ...cat,
      children: buildHierarchy(cat.id)
    }));
}

const hierarchy = buildHierarchy(0);
return { category_tree: hierarchy };

Get Subcategories of a Category​

const categories = msg.category_list;
const parentId = 5; // Technology category
const subcategories = categories.filter(cat => cat.parent === parentId);
return { subcategories: subcategories };

Example Workflows​

Check if Category Exists Before Creating​

1. List Categories
2. Filter results to find matching name
3. If found: Use existing category ID
4. If not found: Create Category → Get new ID

Get Category ID for Post Assignment​

1. List Categories
2. Find category by name (e.g., "Technology")
3. Extract category ID
4. Use ID in Create Post or Update Post

Category Usage Analysis​

1. List Categories
2. Filter by count > 0
3. Sort by count (descending)
4. Export top 10 categories
5. Generate usage report

Sync Categories Between Sites​

Source Site:
  1. List Categories
  2. Export to JSON/CSV

Target Site:
  3. List Categories (check existing)
  4. For each source category:
     - If not exists: Create Category
     - Map old ID to new ID

Best Practices​

  • Cache the category list if using it multiple times in a flow
  • Use the category ID rather than name for reliability
  • Check for empty results before processing
  • Handle the case where expected categories don't exist
  • Store category IDs in variables for reuse
  • Refresh category list after creating new categories
  • Consider filtering categories in your flow logic rather than making multiple API calls

Performance Considerations​

  • List Categories is a lightweight operation
  • Returns all categories in a single request
  • No pagination needed (most sites have < 100 categories)
  • Results can be cached for better performance
  • Filter results in memory rather than making repeated API calls

Troubleshooting​

Empty Category List returned:

  • Verify WordPress site is accessible
  • Check if any categories exist in WordPress
  • Confirm REST API is enabled
  • Check authentication if using credentials

Missing expected categories:

  • Refresh the WordPress admin panel
  • Verify categories weren't deleted
  • Check if you're querying the correct site
  • Clear WordPress cache if using caching plugins

Categories showing count: 0:

  • This is normal for unused categories
  • Categories persist even when empty
  • Use count field to identify active categories

Working with Hierarchies​

Understanding Parent-Child Relationships​

  • parent: 0 - Top-level category (no parent)
  • parent: 5 - Child of category with ID 5
  • Use parent field to build hierarchical structures
  • Multiple levels of nesting are supported

Finding Category Paths​

To get the full path of a category (e.g., "Technology > Web Development"):

function getCategoryPath(categoryId, allCategories) {
  const category = allCategories.find(c => c.id === categoryId);
  if (!category || category.parent === 0) {
    return category ? [category.name] : [];
  }
  const parentPath = getCategoryPath(category.parent, allCategories);
  return [...parentPath, category.name];
}

const path = getCategoryPath(12, msg.category_list);
// Returns: ["Technology", "Web Development"]

Integration Examples​

Export to CSV​

1. List Categories
2. Transform to CSV format:
   - ID, Name, Slug, Description, Parent, Count
3. Write to CSV file

Category Report​

1. List Categories
2. Calculate statistics:
   - Total categories
   - Top-level categories
   - Average posts per category
   - Most used categories
3. Generate HTML/PDF report

Category Cleanup​

1. List Categories
2. Filter by count === 0 (empty categories)
3. Exclude default "Uncategorized"
4. For each empty category:
   - Delete Category
5. Report deleted categories