Variables & Custom Fields Guide

Time to complete: 10-15 minutes to set up first custom variables You'll learn: How to map product fields to prompt variables for dynamic, personalized AI-generated content

Variables and custom fields unlock the full power of AI Product Tools by mapping your existing product data—custom fields, ACF fields, attributes, meta data—directly into AI prompts. This enables dynamic, personalized content that automatically includes brand names, technical specifications, materials, warranties, and any other product-specific information you track in WooCommerce.

Quick Start: Use Custom Variables

Step 1: Understand Variable Types

Variables are placeholders in prompts that get automatically replaced with real product data during AI generation.

Two categories available:

1. Built-in Variables:

   • Standard product data: {title}, {category}, {price}, {sku}, {attributes}
   • System variables: {max_length}, {language}, {style}
   • Available in both Standard and Advanced modes
   • No setup required

2. Custom Variables:

   • Map any product field to a prompt variable
   • WooCommerce custom fields, ACF fields, product meta, taxonomies
   • Unlimited custom variables (no quantity restrictions)
   • Advanced Bulk Generator only
   • Requires one-time mapping setup

How they work:

Prompt Template:
"Write description for {title} made from {material}. Price: {price}."

Replaces with actual data:
"Write description for Organic Cotton T-Shirt made from 100% organic cotton. Price: $29.99."

Step 2: Access Custom Variables Manager

1. Navigate to Products → AI Product Tools → Settings

2. Click Advanced Bulk Generator section in sidebar

3. Scroll down to Custom Variables section:

   • Shows existing mapped variables (if any)
   • Add Custom Variable button
   • Variable list with field sources

4. Click Add Custom Variable button

Step 3: Create Your First Custom Variable

1. Click Add Custom Variable button

2. Modal opens with variable configuration:

   • Variable Name: Descriptive name (e.g., "brand", "material", "warranty")
   • Field Source: Dropdown showing all available fields
   • Variable Code: Auto-generated (e.g., {custom1}, {custom2})

3. Select field source from dropdown:

   • WooCommerce custom fields
   • Advanced Custom Fields (ACF)
   • Product attributes
   • Product meta fields
   • Third-party plugin fields

4. Choose meaningful variable name:

   • Good: {material}, {brand}, {warranty_years}
   • Avoid: {custom1}, {field2}, {x}

5. Click Save Variable

Step 4: Use Variables in Prompts

1. Navigate to Advanced Bulk Generator

2. Edit prompt template to include your custom variables:

Before (generic):
Write a product description for {title} in {category} category.

After (personalized):
Write description for {brand} {title}, a premium {category}
crafted from {material}. Highlight {key_features} and include
{warranty_years}-year warranty coverage. Price: {price}.

3. Test with single product:

   • Select one product with all custom fields populated
   • Generate description
   • Verify variables replaced correctly

4. Review output to confirm variable replacement:

   • Check all custom variables appear with real data
   • Verify no {variable_name} placeholders remain
   • Confirm data accuracy and relevance

Complete End-to-End Example

Let's set up custom variables for a tech gadgets store selling smart home devices with detailed technical specifications.

Store Details:

• Products: 80 smart home devices (cameras, thermostats, locks, sensors)
• Custom Fields: All products have brand, warranty_years, connectivity, power_source fields in ACF
• Goal: Create custom variables for automatic inclusion of technical specs in AI descriptions
• Current Problem: Generic descriptions lack brand names and technical details

Workflow (12 minutes)

Step 1: Audit Available Custom Fields (3 minutes)

1. Navigate to Products → All Products
2. Edit any smart camera product
3. Scroll down to identify custom field sections:
   • ACF Field Group "Technical Specs":
     • brand (text field): "Ring", "Nest", "Arlo"
     • warranty_years (number field): 1, 2, 3
     • connectivity (select field): "Wi-Fi 2.4GHz", "Wi-Fi 5GHz + Bluetooth"
     • power_source (text field): "Battery", "Wired", "Solar + Battery"
   • WooCommerce Attributes:
     • pa_resolution (product attribute): "1080p", "2K", "4K"
     • pa_night_vision (product attribute): "Yes", "No"
4. Document field names for mapping:

   brand → {brand}
   warranty_years → {warranty}
   connectivity → {connectivity}
   power_source → {power}
   pa_resolution → {resolution}

Step 2: Create Custom Variables (5 minutes)

1. Navigate to Settings → Advanced Bulk Generator → Custom Variables
2. Click Add Custom Variable (opens modal)

Variable 1 - Brand: 3. Variable Name: brand 4. Field Source: Select "brand" from ACF fields dropdown 5. Variable Code: Auto-generated as {brand} 6. Click Save Variable (saves, modal closes)

Variable 2 - Warranty: 7. Click Add Custom Variable again 8. Variable Name: warranty 9. Field Source: Select "warranty_years" from ACF fields 10. Variable Code: {warranty} 11. Click Save Variable

Variable 3 - Connectivity: 12. Click Add Custom Variable 13. Variable Name: connectivity 14. Field Source: "connectivity" from ACF 15. Click Save Variable

Variable 4 - Power: 16. Click Add Custom Variable 17. Variable Name: power 18. Field Source: "power_source" from ACF 19. Click Save Variable

Variable 5 - Resolution: 20. Click Add Custom Variable 21. Variable Name: resolution 22. Field Source: "pa_resolution" from product attributes 23. Click Save Variable

Result: 5 custom variables created in ~5 minutes

Step 3: Update Advanced Prompt Template (2 minutes)

1. Scroll up to Advanced Bulk Generator Prompts section
2. Click Edit on Full Description prompt
3. Replace generic prompt:

Old prompt (generic):

Write a product description for {title} in {category} category.
Include key features and benefits. Maximum {max_length} characters.

New prompt (personalized with variables):

Write a compelling product description for the {brand} {title},
a premium {category} designed for smart home security and automation.

Technical Specifications:
- Video Quality: {resolution}
- Connectivity: {connectivity}
- Power: {power}
- Warranty: {warranty}-year manufacturer warranty

Highlight the key features and benefits of this {brand} device.
Explain why the {resolution} video quality and {connectivity}
connectivity make this the ideal choice for homeowners.

Write in professional style, maximum {max_length} characters.

4. Click Save Prompt

Step 4: Test Variable Replacement (2 minutes)

1. Navigate to Advanced Bulk Generator
2. Select single test product: "Ring Video Doorbell Pro 2"
   • brand: Ring
   • warranty_years: 2
   • connectivity: Wi-Fi 5GHz + Bluetooth
   • power_source: Wired
   • pa_resolution: 2K
3. Click Generate button
4. Wait 5-8 seconds for AI generation
5. Preview generated content:

Experience premium home security with the Ring Video Doorbell Pro 2,
a cutting-edge smart doorbell designed for comprehensive property protection.
This advanced device captures crystal-clear 2K video footage with HDR,
ensuring you never miss important details day or night.

Technical Specifications:
- Video Quality: 2K HDR with head-to-toe view
- Connectivity: Wi-Fi 5GHz + Bluetooth for reliable performance
- Power: Hardwired for continuous 24/7 operation
- Warranty: 2-year manufacturer warranty for peace of mind

Ring's industry-leading motion detection technology and two-way audio
communication make the Video Doorbell Pro 2 perfect for homeowners seeking
professional-grade security. The 2K video clarity provides exceptional
detail, while dual-band Wi-Fi 5GHz + Bluetooth ensures stable connectivity
even in busy network environments.

6. Verify variable replacement:
   • ✅ {brand} → "Ring" (appears 2 times)
   • ✅ {resolution} → "2K" (appears 3 times, contextually)
   • ✅ {connectivity} → "Wi-Fi 5GHz + Bluetooth" (appears 2 times)
   • ✅ {power} → "Wired" / "Hardwired" (natural language variation)
   • ✅ {warranty} → "2-year" (formatted correctly)

Total time: 12 minutes ✅ Result: Custom variables working perfectly, technical specs automatically included in every description.

Before vs After Comparison:

Before (without variables):

This video doorbell offers high-quality video and smart features for
your home. It connects wirelessly and provides reliable performance.
Great for monitoring your front door with mobile app notifications.

Issues:

• No brand mentioned (generic, could be any doorbell)
• Vague technical details ("high-quality video" vs specific resolution)
• No warranty information
• Missing specific connectivity details

After (with variables):

Experience premium home security with the Ring Video Doorbell Pro 2,
a cutting-edge smart doorbell designed for comprehensive property protection.
This advanced device captures crystal-clear 2K video footage with HDR...
[Technical Specifications section with specific details]
Ring's industry-leading motion detection... 2K video clarity... dual-band
Wi-Fi 5GHz + Bluetooth... 2-year manufacturer warranty...

Improvements:

• ✅ Brand mentioned prominently (Ring)
• ✅ Specific technical details (2K, Wi-Fi 5GHz + Bluetooth, Wired)
• ✅ Warranty coverage explicit (2-year)
• ✅ Professional, detailed, personalized content

Built-in Variables Reference

Product Data Variables

Available in both Standard and Advanced modes, automatically populated from WooCommerce product data:

System Variables

Control AI generation parameters:

Custom Variables

Advanced Bulk Generator only - unlimited custom field mapping:

Example custom variable setup:

Prompt with custom variables:
"Write description for {brand} {title}, a premium {category} made from {material}.
Includes {warranty}-year warranty. Price: {price}."

Actual data for product:
- brand: Patagonia
- title: Organic Cotton T-Shirt
- category: Clothing
- material: 100% organic cotton
- warranty: 2
- price: $29.99

Result sent to AI:
"Write description for Patagonia Organic Cotton T-Shirt, a premium Clothing
made from 100% organic cotton. Includes 2-year warranty. Price: $29.99."

Variable Syntax & Usage

Basic Syntax Rules

Valid examples:

• {title}, {price}, {category} (built-in, lowercase)
• {brand}, {material}, {warranty} (custom, descriptive)
• {tech_specs}, {shipping_time}, {care_instructions} (multi-word with underscores)

Invalid examples:

• {Title} (wrong case for built-in variable)
• {warranty years} (contains space)
• {custom-field} (hyphen not allowed)
• custom1 (missing curly braces)

Variable Placement in Prompts

Strategic placement:

1. Context Setting (beginning):

   Write a {style} product description for {brand} {title},
   a premium {category} product.

2. Product Details (middle):

   Product specifications:
   - Material: {material}
   - Dimensions: {dimensions}
   - Warranty: {warranty}-year coverage

3. Instructions (end):

   Write in {language}, maximum {max_length} characters,
   targeting {target_audience}.

Default Values for Empty Fields

Problem: What happens if a product doesn't have a custom field populated?

Solution: AI typically handles gracefully by omitting or substituting natural language:

Prompt with variable:
"Made from {material} with {warranty}-year warranty."

Product WITH fields populated:
"Made from 100% organic cotton with 2-year warranty."

Product WITHOUT fields populated:
"Crafted with premium materials and backed by manufacturer warranty."
(AI naturally rephrases when data unavailable)

Best practice: Always test prompts with products missing some custom fields to ensure graceful handling.

Custom Field Integration

Supported Field Types

AI Product Tools automatically detects and makes available:

WooCommerce Native Fields

Custom Product Fields:

• Fields added by plugins like Advanced Custom Fields (ACF)
• Fields from Product Builder plugins
• Any custom data you add to product edit screens

Product Attributes:

• Global attributes (e.g., Color, Size, Material)
• Product-specific attributes for individual products
• Variation attributes for variable products

Product Meta Fields:

• Custom fields from other plugins
• Any additional product data fields

Advanced Custom Fields (ACF)

All ACF field types supported:

ACF field groups:

• Plugin automatically detects all ACF field groups assigned to Products
• Lists all fields from all groups in field source dropdown
• No additional configuration required

Third-Party Plugin Fields

Commonly supported plugins:

Field Discovery

How it works:

The plugin automatically finds all custom fields available in your products and shows them in the Field Source dropdown when creating variables. This includes:

• WooCommerce custom fields
• Advanced Custom Fields (ACF)
• Product attributes
• Fields from third-party plugins (WooCommerce Brands, etc.)

If a field doesn't appear:

1. Check if the plugin creating that field is active

   • Example: If using ACF fields, ensure Advanced Custom Fields plugin is activated
   • Deactivated plugin = fields won't show in dropdown

2. Make sure the field actually exists on your products

   • Go to Products → Edit any product
   • Look for the custom field section
   • If you can see and edit the field, it exists

3. Contact support if needed:

   • Email support with the field name and which plugin creates it
   • Support can help map fields that don't appear automatically
   • See Support Resources

Advanced Variable Usage

Combining Multiple Variables

Create rich, detailed prompts:

Comprehensive product prompt:

Write a detailed product description for the {brand} {title}.

**Product Overview:**
This {category} is expertly crafted from {material} and designed for
{target_audience}. Priced at {price} (regular {regular_price}), it
represents exceptional value in the {category} category.

**Technical Specifications:**
- Dimensions: {dimensions}
- Weight: {weight}
- Connectivity: {connectivity}
- Power: {power_source}
- Compatibility: {compatibility}

**Features & Benefits:**
{key_features}

**Warranty & Support:**
Backed by a {warranty}-year manufacturer warranty and {support_type}
customer support.

**Additional Information:**
{care_instructions}

Write in {language}, {style} tone, maximum {max_length} characters.

Result: AI receives comprehensive product context, generates highly detailed, accurate descriptions.

Variable Best Practices

Naming Conventions

Prompt Design Strategy

Structure for maximum effectiveness:

1. Start broad: Product type, brand, category
2. Add specifics: Technical details, materials, features
3. Include benefits: Why customer should care
4. Finish with constraints: Style, length, language

Progressive detail example:

Level 1 (Basic - built-in variables only):
"Write description for {title} in {category}. Price: {price}."

Level 2 (Enhanced - few custom variables):
"Write description for {brand} {title}, a {category} made from {material}."

Level 3 (Comprehensive - many custom variables):
"Write description for {brand} {title}, a premium {category} crafted from
{material}. Features include {key_features}. Dimensions: {dimensions},
Weight: {weight}. Includes {warranty}-year warranty. Perfect for {target_audience}."

Result: More variables = more personalized, accurate content.

Quality Assurance

Testing checklist:

Troubleshooting

Issue: Variable not replacing with product data

Symptoms:

• Generated content shows {variable_name} instead of actual data
• Variable appears as literal text in output
• Some variables work, others don't
• Previously working variable stopped replacing

Cause: Variable name mismatch, field mapping error, or empty field value

Solution:

1. Verify variable name spelling:

   • Navigate to Settings → Advanced Bulk Generator → Custom Variables
   • Find your variable in the list
   • Confirm exact spelling matches what's in prompt
   • Variable names are case-sensitive: {Brand} ≠ {brand}
   • Check for typos: {waranty} vs {warranty}

2. Confirm field mapping:

   • Click Edit on the variable in Custom Variables list
   • Verify Field Source shows correct custom field
   • Test by selecting different field source
   • Save and regenerate content

3. Check if field has value:

   • Edit the product you're testing with
   • Scroll to custom field section (ACF, product data, etc.)
   • Verify the mapped field actually has content
   • If empty, populate field and try again
   • Variables for empty fields may show as {variable} or be omitted by AI

4. Test with known-working product:

   • Find a product where you KNOW the custom field is populated
   • Generate description for that product
   • If variable replaces correctly: Original product has empty field
   • If variable still doesn't replace: Mapping or syntax issue

5. Check field source availability:

   • Some fields require specific plugins active (ACF, WooCommerce Brands)
   • Deactivated plugins = fields become unavailable
   • Verify all required plugins are active
   • Re-save Custom Variable mapping if plugin was temporarily deactivated

6. Clear plugin cache:

   • Navigate to Settings → Advanced Bulk Generator
   • Scroll to bottom of page
   • Click Clear Cache button (if available)
   • Or deactivate/reactivate AI Product Tools plugin
   • Regenerate content with cleared cache

Related: Settings Configuration, Advanced Bulk Generator

Issue: Generated content quality poor with custom variables

Symptoms:

• AI mentions variable names awkwardly ("the warranty years is 2")
• Repetitive phrasing when multiple variables used
• Unnatural integration of technical data
• Variables interrupt content flow
• Output sounds robotic or templated

Cause: Prompt structure doesn't guide AI on how to use variable data naturally

Solution:

1. Improve prompt phrasing around variables:

   Before (awkward):

   Write description for {title}. Material is {material}.
   Warranty is {warranty} years. Price is {price}.

   After (natural):

   Write a compelling description for the {title}, expertly crafted
   from {material}. Backed by a {warranty}-year warranty. Price: {price}.

   Why better: Integrates variables into complete sentences, not fragments.

2. Add context for technical variables:

   Before (data dump):

   {title} specs: {resolution}, {connectivity}, {power}.

   After (contextual):

   The {title} delivers stunning {resolution} video quality with reliable
   {connectivity} connectivity, powered by {power} for continuous operation.

   Why better: Explains what the specs mean, not just listing them.

3. Use variables as guidance, not scripts:

   Before (forced inclusion):

   Mention the {material} material and {warranty}-year warranty explicitly.

   After (flexible instruction):

   Highlight the premium {material} construction and {warranty}-year warranty
   coverage, explaining the benefits to customers.

   Why better: Gives AI freedom to integrate naturally, not force-mention.

4. Test with different AI models:

   • Navigate to Settings → API Settings
   • Try switching to higher-tier model:
     • OpenAI: GPT-4o instead of GPT-4o-mini
     • Gemini: 2.5 Pro instead of 2.5 Flash
   • Premium models often better at natural variable integration
   • Generate same product with new model
   • Compare quality improvement

5. Reduce variable density:

   • Don't use all available variables in every prompt
   • Select 4-6 most important variables per prompt
   • Too many variables = robotic, template-feel content
   • Test with fewer variables, assess if quality improves

6. Add narrative structure:

   Write a story-driven description for the {brand} {title}.
   
   Start by introducing this {category} and its premium {material} construction.
   Then explain how the {key_features} solve customer problems.
   Highlight the {warranty}-year warranty as a trust signal.
   End with a clear value proposition at {price}.

   Why better: Guides AI through narrative flow, variables support story.

Related: AI Smart Parameters, Settings Prompt Customization

Issue: Custom field not appearing in variable dropdown

Symptoms:

• Can't find expected custom field in Field Source dropdown
• Field exists on product edit screen but not in variable mapper
• Other fields from same plugin appear, but specific field missing
• Recently added field doesn't show in dropdown

Cause: Field not registered correctly, plugin conflict, or access permissions issue

Solution:

1. Verify field is actually a custom field:

   • Edit any product with the field visible
   • Check if it's a standard WooCommerce field:
     • Standard fields (title, price, SKU, description): Already available as built-in variables, no mapping needed
     • Custom fields (brand, warranty, material, etc.): Need to be mapped as custom variables
   • Custom fields are usually added by plugins like ACF or WooCommerce Brands
   • If unsure, contact support with the field name

2. Check field location:

   • Product Data tabs (General, Inventory, Shipping): Usually WooCommerce defaults, not custom fields
   • Below product data tabs (ACF field groups): These ARE custom fields
   • Sidebar metaboxes: May be custom fields or plugin-specific
   • Only fields from supported sources appear in dropdown

3. Verify plugin compatibility:

   • Navigate to Plugins → Installed Plugins
   • Confirm these are active:
     • Advanced Custom Fields (if using ACF fields)
     • WooCommerce Brands (if using brand fields)
     • Any plugin that creates the custom field
   • If plugin is inactive, field won't be available
   • Activate plugin and refresh Settings page

4. Check field registration:

   • Some fields are "private" and may not appear in dropdown for security reasons
   • If a field is created by custom code, it may need to be registered correctly
   • Contact support if you believe a field should appear but doesn't

5. Force field detection refresh:

   • Go to Settings → Advanced Bulk Generator → Custom Variables
   • Scroll to bottom of Custom Variables section
   • Click Refresh Field List button (if available)
   • Or deactivate/reactivate AI Product Tools plugin completely
   • This forces plugin to re-scan all available custom fields
   • Return to Add Custom Variable modal, check dropdown again

6. Manual field key entry (if dropdown doesn't show field):

   • Contact support at support page
   • Provide the exact field key name (from step 1)
   • Provide the plugin creating the field
   • Support can whitelist the field for manual entry
   • You'll be able to type field key directly instead of selecting from dropdown

7. Fallback: Use product attributes instead:

   • If custom field can't be mapped, consider converting to product attribute
   • Navigate to Products → Attributes
   • Create new global attribute (e.g., "Brand", "Material")
   • Add attribute to products manually or via import
   • Product attributes (pa_{attribute}) automatically available in variable dropdown

Related: Troubleshooting Guide, Support Resources

When to Use Custom Variables

Ideal Use Cases:

Best Practices

Variable Strategy

Do's:

• ✅ Use descriptive variable names ({warranty} not {custom1})
• ✅ Test each variable with 2-3 products before bulk operations
• ✅ Map only the most important custom fields (4-6 variables optimal)
• ✅ Document variable mappings for team reference
• ✅ Integrate variables naturally in prompt sentences

Don'ts:

• ❌ Don't create variables for fields rarely populated (many products missing data)
• ❌ Don't use ALL available fields in every prompt (causes robotic content)
• ❌ Don't forget to test with products missing some custom field data
• ❌ Don't use technical field keys as variable names (field_abc123)

Prompt Optimization

Progressive enhancement:

1. Start simple - Test with 1-2 custom variables
2. Evaluate quality - Does adding variables improve content?
3. Add gradually - Introduce additional variables one at a time
4. Monitor output - Watch for robotic phrasing or awkward integration
5. Refine prompts - Adjust wording around variables for natural flow

What You've Learned

Congratulations! You now know how to:

• ✅ Understand difference between built-in and custom variables
• ✅ Access and use the Custom Variables manager
• ✅ Create custom variable mappings from product fields to prompt variables
• ✅ Use variables in Advanced Bulk Generator prompts for personalized content
• ✅ Troubleshoot variable replacement issues (syntax, mapping, empty fields)
• ✅ Integrate custom fields from ACF, WooCommerce, and third-party plugins

Next Steps

Immediate Actions:

• Generate with variables - Use your custom variables in bulk operations
• Optimize prompts - Refine prompt templates with variable integration
• Test AI models - Compare how different models handle variable-rich prompts

Advanced Workflows:

• Set up automation - Auto-generate with variables for new products
• Use Smart Parameters - Combine variables with automatic AI optimization
• Learn best practices - Master advanced variable strategies

Related Topics

• Advanced Bulk Generator - Use custom variables in bulk generation
• Settings Configuration - Configure prompts with variables
• AI Smart Parameters - Automatic optimization for variable-rich prompts
• Best Practices - Advanced variable and prompt strategies
• Troubleshooting Guide - Common variable issues and solutions