MetaBox Integration for WordPress & WooCommerce

Comprehensive guide for working with MetaBox custom fields using the MB REST API extension.

When to Use This Skill

Activate this skill when user needs help with:

•Getting custom fields from posts, pages, or custom post types
•Updating MetaBox custom fields
•Working with custom fields on taxonomies (categories, tags)
•Managing user or comment custom fields
•Accessing MetaBox settings pages
•Understanding MetaBox REST API structure
•Troubleshooting MetaBox field access

What is MetaBox?

MetaBox is a powerful WordPress plugin for creating custom fields (meta boxes) without code. The MB REST API extension integrates these custom fields into WordPress's native REST API, making them accessible programmatically.

Key Features

•Seamless Integration: Custom fields appear in standard WordPress endpoints
•No New Endpoints: Uses existing /wp/v2/{post-type}/{id} endpoints
•Auto-Formatting: Complex field types (maps, images) include enhanced data
•Full CRUD Support: Get and update custom fields via REST API
•Settings Pages: Special endpoint for MetaBox settings pages

Prerequisites

•MetaBox Plugin: Install and activate MetaBox on your WordPress site
•
MB REST API Extension: Install and activate the MB REST API extension
- •Available at: https://metabox.io/plugins/mb-rest-api/
- •Can be installed via WordPress plugin installer or composer
•WordPress Configuration: Your WordPress site must be configured with Application Passwords (see setup-configuration skill)

How MetaBox REST API Works

Data Structure

MetaBox adds custom field data to standard WordPress responses under a meta_box key:

json

{
  "id": 123,
  "title": "My Post",
  "content": "...",
  "meta_box": {
    "field_1": "value_1",
    "field_2": "value_2",
    "custom_image": {
      "url": "https://example.com/image.jpg",
      "width": 1200,
      "height": 800
    }
  }
}

Endpoint Structure

Content Type	Endpoint	Example
Posts	`/wp/v2/posts/{id}`	`/wp/v2/posts/123`
Pages	`/wp/v2/pages/{id}`	`/wp/v2/pages/456`
Custom Post Types	`/wp/v2/{post_type}/{id}`	`/wp/v2/products/789`
Categories	`/wp/v2/categories/{id}`	`/wp/v2/categories/10`
Tags	`/wp/v2/tags/{id}`	`/wp/v2/tags/20`
Custom Taxonomies	`/wp/v2/{taxonomy}/{id}`	`/wp/v2/portfolio-tags/15`
Users	`/wp/v2/users/{id}`	`/wp/v2/users/5`
Comments	`/wp/v2/comments/{id}`	`/wp/v2/comments/50`
Settings Pages	`/meta-box/v1/settings-page?id={page_id}`	`/meta-box/v1/settings-page?id=my-settings`

Available Tools

Post/Page/CPT Custom Fields

Get Custom Fields:

code

metabox_get_post_fields
- post_type: "posts", "pages", or custom post type slug
- id: Post ID

Update Custom Fields:

code

metabox_update_post_fields
- post_type: Post type slug
- id: Post ID
- fields: Object with field_id: value pairs

Example:

javascript

// Get custom fields for a post
{
  "post_type": "posts",
  "id": 123
}

// Update custom fields
{
  "post_type": "posts",
  "id": 123,
  "fields": {
    "author_bio": "Orlando Bruno is a data scientist...",
    "featured_flag": true,
    "reading_time": 5
  }
}

Taxonomy Term Custom Fields

Get Term Fields:

code

metabox_get_term_fields
- taxonomy: "categories", "tags", or custom taxonomy slug
- id: Term ID

Update Term Fields:

code

metabox_update_term_fields
- taxonomy: Taxonomy slug
- id: Term ID
- fields: Field updates

Example:

javascript

// Get category custom fields
{
  "taxonomy": "categories",
  "id": 10
}

// Update custom fields
{
  "taxonomy": "categories",
  "id": 10,
  "fields": {
    "category_color": "#3498db",
    "category_icon": "fa-rocket"
  }
}

User Custom Fields

Get User Fields:

code

metabox_get_user_fields
- id: User ID

Update User Fields:

code

metabox_update_user_fields
- id: User ID
- fields: Field updates

Example:

javascript

// Update user custom fields
{
  "id": 5,
  "fields": {
    "user_twitter": "@orlandobruno",
    "user_linkedin": "linkedin.com/in/orlandobruno",
    "user_expertise": ["AI", "Data Science", "Music"]
  }
}

Comment Custom Fields

Get Comment Fields:

code

metabox_get_comment_fields
- id: Comment ID

Update Comment Fields:

code

metabox_update_comment_fields
- id: Comment ID
- fields: Field updates

Settings Pages

Settings pages are special MetaBox pages that store site-wide configuration.

IMPORTANT: Settings pages require:

•Authentication (WordPress Application Password)
•User capability matching the settings page configuration
•Both read and write operations require authentication

Get Settings Page:

code

metabox_get_settings_page
- id: Settings page ID (as configured in MetaBox)

Update Settings Page:

code

metabox_update_settings_page
- id: Settings page ID
- fields: Field updates

Example:

javascript

// Get site settings
{
  "id": "site-options"
}

// Update site settings
{
  "id": "site-options",
  "fields": {
    "footer_text": "© 2025 Orlando Bruno",
    "analytics_id": "UA-123456-1",
    "enable_maintenance": false
  }
}

Field Types and Auto-Formatting

MetaBox automatically formats complex field types:

Image/File Fields

json

{
  "featured_image": {
    "url": "https://example.com/image.jpg",
    "width": 1200,
    "height": 800,
    "full_url": "https://example.com/image-full.jpg"
  }
}

Map Fields

json

{
  "location": {
    "latitude": 9.7489,
    "longitude": -83.7534,
    "address": "San José, Costa Rica",
    "zoom": 12
  }
}

Relationship Fields

json

{
  "related_posts": [123, 456, 789]
}

Hiding Fields from REST API

You can hide specific fields from REST API responses:

In MB Builder:

•Edit field
•Check "Hide from REST API" option

In Code:

php

'hide_from_rest' => true

Hidden fields will not appear in meta_box responses and cannot be updated via REST API.

Common Workflows

1. Getting All Custom Fields for a Post

javascript

// Use metabox_get_post_fields
{
  "post_type": "posts",
  "id": 123
}

// Response includes meta_box object with all fields
{
  "success": true,
  "data": { /* full post data */ },
  "meta_box": {
    "field_1": "value",
    "field_2": "value"
  }
}

2. Updating Specific Custom Fields

javascript

// Update only the fields you want to change
{
  "post_type": "posts",
  "id": 123,
  "fields": {
    "subtitle": "New subtitle",
    "author_note": "Updated author note"
  }
}

// Other fields remain unchanged

3. Working with WooCommerce Products

javascript

// WooCommerce products are a custom post type
{
  "post_type": "product",
  "id": 789,
  "fields": {
    "product_warranty": "2 years",
    "product_manual": "https://example.com/manual.pdf",
    "eco_friendly": true
  }
}

4. Bulk Field Updates

For multiple posts, iterate through IDs:

javascript

// Update custom fields for multiple posts
const postIds = [123, 456, 789];

for (const id of postIds) {
  await metabox_update_post_fields({
    post_type: "posts",
    id: id,
    fields: {
      "review_status": "reviewed",
      "reviewed_by": 5
    }
  });
}

Troubleshooting

"meta_box key not found in response"

Cause: MB REST API extension not installed or activated

Solution:

•Install MB REST API extension
•Activate the extension in WordPress
•Test with metabox_get_post_fields on a post with custom fields

"Authentication required"

Cause: Settings pages always require authentication

Solution:

•Ensure WordPress Application Password is configured (see setup-configuration skill)
•Verify user has required capability for settings page

"Field not updating"

Possible Causes:

•Field is set to "Hide from REST API"
•Field ID doesn't match (check exact field ID in MetaBox)
•Invalid field value type (e.g., passing string to number field)

Solution:

•Verify field is visible in REST API
•Check field ID exactly matches MetaBox configuration
•Ensure value type matches field type

"Custom post type fields not accessible"

Cause: Custom post type not registered in REST API

Solution:

•Ensure custom post type has 'show_in_rest' => true in registration
•Check REST base name ('rest_base' => 'custom-slug')
•Use correct post type slug in metabox_get_post_fields

Best Practices

•
Field Naming: Use snake_case for field IDs (e.g., author_bio, not Author Bio)
•
Batch Operations: For large datasets, consider pagination and rate limiting
•
Error Handling: Always check response success before processing data
•
Field Validation: Validate field values before updating to prevent data corruption
•
Documentation: Keep track of field IDs and their purposes for your project

Integration with WooCommerce

MetaBox works seamlessly with WooCommerce products (which are custom post types):

javascript

// Add custom fields to WooCommerce products
{
  "post_type": "product",
  "id": 456,
  "fields": {
    "supplier_name": "Acme Corp",
    "warranty_period": "24 months",
    "eco_certification": true,
    "custom_specs": {
      "weight": "2.5kg",
      "dimensions": "30x20x15cm"
    }
  }
}

Security Considerations

•HTTPS Required: All REST API calls require HTTPS
•Authentication: Updates require WordPress Application Password
•Capabilities: Users must have edit capabilities for the content type
•Field Visibility: Sensitive fields should be hidden from REST API
•Validation: Always validate and sanitize field values

Resources

•Official Documentation: https://docs.metabox.io/extensions/mb-rest-api/
•MetaBox Website: https://metabox.io
•Field Types Reference: https://docs.metabox.io/field-settings/
•WordPress REST API: https://developer.wordpress.org/rest-api/

Testing MetaBox Integration

Use the check_connection tool to verify MetaBox is working:

javascript

// Test connection (includes MetaBox check)
check_connection

This will return:

json

{
  "metabox": {
    "success": true,
    "hasMetaBox": true,
    "message": "MetaBox REST API is active and working"
  }
}

If hasMetaBox is false, the MB REST API extension may not be installed.

Last Updated: 2025-12-26 Plugin Version: 0.1.0