Documentation Overview

Wallet Up – WPForms Quantity Controls is a WordPress plugin that enhances WPForms by adding intuitive quantity selectors to payment checkbox fields. This allows users to select multiple quantities of each product in a form, improving the shopping experience and potentially increasing average order value. This comprehensive documentation covers everything from installation to advanced customization and developer reference.

Installation
Getting Started
Features
Settings and Configuration
Usage Guide
Troubleshooting
Developer Documentation
Compatibility
Localization
Frequently Asked Questions
Changelog
Support

Installation

Requirements

WordPress 5.2 or higher
WPForms 1.7.0 or higher
At least one WPForms payment addon (PayPal, Stripe, Square, etc.)
PHP 7.2 or higher

Installation Steps

Upload the Plugin:
- Download the wallet-up-wpforms-qty-ctrls.zip file
- Navigate to WordPress Admin → Plugins → Add New → Upload Plugin
- Upload the zip file and click “Install Now”
- Alternatively, unzip the file and upload the wallet-up-wpforms-qty-ctrls folder to the /wp-content/plugins/ directory via FTP
Activate the Plugin:
- Once installed, click “Activate Plugin”
- Ensure WPForms and at least one payment addon are active
Verify Installation:
- Navigate to Settings → Wallet Up Qty to confirm the plugin is properly installed
- The plugin should work immediately with existing WPForms payment forms

Getting Started

After installation, the plugin will automatically enhance any WPForms that include payment checkbox fields. No initial configuration is required to start using the quantity controls.

Quick Start Guide:

Create or edit a WPForms form with payment checkbox fields
Preview the form
When selecting a payment checkbox, quantity controls will automatically appear
Users can increase or decrease the quantity for each selected item
The form total will automatically update to reflect the quantities

Features

Core Features

Modern Quantity Controls – Stylish, user-friendly controls that match your site’s aesthetic
Real-time Total Updates – Automatically calculates and updates the form total as quantities change
Mobile Optimized – Fully responsive design for all device sizes
Payment Gateway Integration – Works with all WPForms payment gateways
Conditional Logic Support – Fully compatible with WPForms conditional logic
Multi-page Form Support – Maintains quantities when navigating between form pages

Accessibility Features

Keyboard Navigation – Allows using Tab, Enter, Space, and arrow keys to control quantities
ARIA Live Regions – Announces total updates to screen readers
High Contrast Mode – Improved visibility for users with vision impairments
Focus Styling – Enhanced focus indicators for keyboard navigation
RTL Language Support – Properly displays in Right-to-Left languages

Performance Features

Lazy Loading – Optimized loading for forms below the fold
State Preservation – Maintains quantity selections during page navigation and form submission
Debounced Updates – Prevents excessive calculations when making rapid changes

Settings and Configuration

Access plugin settings by navigating to Settings → Wallet Up Qty in your WordPress admin dashboard.

General Settings

Setting	Description	Default
Maximum Quantity	Sets the maximum quantity users can select for any item	99
Settings Page	Enable/disable the settings page (requires restart)	Enabled
Debug Mode	Enable logging for troubleshooting	Disabled

Display Settings

Setting	Description	Default
Primary Color	Main color for buttons and highlights	#0073aa
Secondary Color	Secondary color for text and borders	#555
Success Color	Color for success messages and indicators	#4caf50
Error Color	Color for error messages and indicators	#f44336
Animation Duration	Duration of animations in milliseconds	300
Mobile Breakpoint	Width in pixels where mobile layout is applied	600
Larger Touch Targets	Enables larger touch targets on mobile devices	Enabled
Custom CSS	Add custom CSS for further customization	Empty

Advanced Settings

Setting	Description	Default
High Contrast Mode	Adds support for Windows High Contrast Mode	Disabled
Enhanced Accessibility	Adds enhanced focus styles and accessibility features	Enabled
RTL Support	Enables support for Right-to-Left languages	Enabled
ARIA Live Regions	Adds ARIA live regions for dynamic content	Enabled
Lazy Loading	Enables lazy loading for quantity controls	Enabled
Keyboard Navigation	Enables keyboard navigation for quantity controls	Enabled

Integration Settings

Setting	Description	Default
WPForms Currency Format	Uses WPForms currency formatting	Enabled
Error Indicators	Shows visual indicators for errors	Enabled
Hide on Disabled Forms	Hides controls on forms with disabled fields	Enabled
Dynamic Form Detection	Enables detection of dynamically loaded forms	Enabled
AJAX Controls	Updates controls via AJAX when needed	Enabled
Preserve State	Preserves quantity state during page navigation	Enabled

Tools

The Tools tab provides utilities for managing the plugin:

Reset Settings – Reset all settings to default values
Clear Logs – Clear all saved error logs
Test Controls – Preview how the quantity controls will look with current settings

Logs

The Logs tab displays error logs when Debug Mode is enabled, showing:

Time – When the error occurred
Level – Error level (error, warning, info)
Message – Detailed error message

Usage Guide

Basic Usage

Create a Form with Payment Fields:
- Using WPForms, create a form that includes payment checkbox fields
- Add pricing information to each checkbox option
Publish Your Form:
- Add the form to a page or post using the WPForms block or shortcode
- No additional configuration is required
User Experience:
- When a user checks a payment checkbox, quantity controls appear
- Users can increase or decrease quantities using the controls
- The form total automatically updates to reflect the quantity selections

Advanced Usage

Using with Conditional Logic

The plugin is fully compatible with WPForms conditional logic:

Set up conditional logic as you normally would in WPForms
Quantity controls will automatically appear/disappear based on conditional logic rules
When fields are shown/hidden, quantities are preserved

Using with Multi-page Forms

For multi-page forms:

Set up a multi-page form with payment fields
Enable “Preserve State” in plugin settings (enabled by default)
Quantities will be maintained when users navigate between pages

Use with Product Variations

For forms with product variations:

Create separate checkbox items for each product variation
Set up conditional logic to show/hide variations based on user selections
Quantity controls will work independently for each variation

Troubleshooting

Common Issues

Quantity controls don’t appear

Possible causes:

Payment checkbox field not properly configured with pricing
WPForms payment addon not active
Conflicting JavaScript from another plugin

Solutions:

Verify that payment checkbox fields have prices set
Check that at least one WPForms payment addon is active
Temporarily disable other plugins to check for conflicts

Totals not updating correctly

Possible causes:

Custom WPForms calculations overriding quantities
JavaScript errors

Solutions:

Check browser console for JavaScript errors
Enable debug mode to log more detailed information
Verify that WPForms calculations are compatible with quantity data

Style conflicts with theme

Possible causes:

Theme CSS overriding plugin styles
Custom CSS causing conflicts

Solutions:

Use the Custom CSS setting to override conflicting styles
Adjust colors in Display Settings to better match your theme
Use browser inspector to identify conflicting CSS rules

Debugging

To troubleshoot issues:

Enable Debug Mode in General Settings
Reproduce the issue
Check the Logs tab for error messages
Check browser console for JavaScript errors
If reporting an issue, include both log data and console errors

Developer Documentation

Hooks and Filters

`walletup_qty_settings`

Modify plugin settings.

/**
 * Customize plugin settings
 * 
 * @param array $settings Current settings
 * @return array Modified settings
 */
function my_custom_walletup_settings($settings) {
    // Change maximum quantity
    $settings['max_quantity'] = 50;
    
    // Change primary color
    $settings['primary_color'] = '#e91e63';
    
    return $settings;
}
add_filter('walletup_qty_settings', 'my_custom_walletup_settings');

`walletup_qty_disable_controls`

Disable quantity controls for specific forms or pages.

/**
 * Disable quantity controls on specific pages
 * 
 * @param bool $disable Whether to disable controls
 * @param int $post_id Current post ID
 * @return bool Modified disable state
 */
function disable_qty_on_specific_form($disable, $post_id) {
    // Disable on a specific page
    if ($post_id === 123) {
        return true;
    }
    
    // Disable for a specific form ID
    global $wpforms_displayed;
    if (isset($wpforms_displayed) && in_array(456, $wpforms_displayed)) {
        return true;
    }
    
    return $disable;
}
add_filter('walletup_qty_disable_controls', 'disable_qty_on_specific_form', 10, 2);

`walletup_qty_process_quantities`

Modify processed quantities data before it’s applied to form fields.

/**
 * Modify quantities data before processing
 * 
 * @param array $fields Form fields
 * @param array $quantities Quantity data
 * @param array $form_data Form data
 * @return array Modified fields
 */
function my_custom_quantity_processor($fields, $quantities, $form_data) {
    // Apply maximum quantity limit per product
    foreach ($quantities as $field_id => $choices) {
        foreach ($choices as $choice_id => $qty) {
            // Limit specific product to max of 5
            if ($field_id == 10 && $choice_id == 2) {
                $quantities[$field_id][$choice_id] = min($qty, 5);
            }
        }
    }
    
    return $fields;
}
add_filter('walletup_qty_process_quantities', 'my_custom_quantity_processor', 10, 3);

`walletup_qty_process_payment`

Modify payment data after quantity processing.

/**
 * Add volume discounts based on quantity
 * 
 * @param array $payment_data Payment data
 * @param array $quantities Quantity data
 * @param array $form_data Form data
 * @return array Modified payment data
 */
function add_volume_discounts($payment_data, $quantities, $form_data) {
    // Define discount tiers
    $discount_tiers = [
        5 => 0.05, // 5% discount for 5+ items
        10 => 0.10, // 10% discount for 10+ items
        20 => 0.15, // 15% discount for 20+ items
    ];
    
    // Calculate total quantity
    $total_quantity = 0;
    foreach ($payment_data['items'] as $item) {
        $total_quantity += isset($item['quantity']) ? $item['quantity'] : 1;
    }
    
    // Determine discount percentage
    $discount_percentage = 0;
    foreach ($discount_tiers as $qty => $discount) {
        if ($total_quantity >= $qty) {
            $discount_percentage = $discount;
        }
    }
    
    // Apply discount if applicable
    if ($discount_percentage > 0) {
        // Create discount item
        $discount_amount = $payment_data['total'] * $discount_percentage;
        
        // Add discount as a line item
        $payment_data['items'][] = [
            'name' => sprintf('Volume Discount (%d%%)', $discount_percentage * 100),
            'amount' => -$discount_amount,
            'type' => 'discount',
        ];
        
        // Update total
        $payment_data['total'] -= $discount_amount;
    }
    
    return $payment_data;
}
add_filter('walletup_qty_process_payment', 'add_volume_discounts', 10, 3);

JavaScript API

The plugin exposes a JavaScript API through the global WalletUpQty object.

Initialize Controls Manually

jQuery(document).ready(function($) {
    // Initialize quantity controls for all forms
    if (typeof WalletUpQty !== 'undefined') {
        WalletUpQty.initializeQuantityControls();
    }
});

Update Totals Manually

jQuery(document).ready(function($) {
    // Update totals for a specific form
    if (typeof WalletUpQty !== 'undefined') {
        var $form = $('#wpforms-form-123');
        WalletUpQty.updateTotals($form);
    }
});

Format Currency

jQuery(document).ready(function($) {
    // Format a currency amount using plugin settings
    if (typeof WalletUpQty !== 'undefined') {
        var formattedAmount = WalletUpQty.formatCurrency(49.99);
        console.log(formattedAmount); // "$49.99" (depending on currency settings)
    }
});

Additional Methods

WalletUpQty.initializeForForm($form) – Initialize controls for a specific form
WalletUpQty.initializeForField(fieldId) – Initialize controls for a specific field
WalletUpQty.saveState($form) – Save the current quantity state for a form
WalletUpQty.restoreState($form) – Restore quantity state for a form

CSS Customization

Using the Custom CSS Setting

The easiest way to customize styles is through the Custom CSS setting in Display Settings:

/* Example: Change quantity button background */
.walletup-quantity-button {
    background-color: #f5f5f5;
}

/* Example: Modify button hover state */
.walletup-quantity-button:hover {
    background-color: #e0e0e0;
}

/* Example: Customize input text */
.walletup-quantity-input {
    font-weight: bold;
    color: #333;
}

CSS Variables

The plugin uses CSS variables that can be overridden in your theme:

/* Override in your theme's CSS */
.wpforms-field-payment-checkbox {
    --walletup-primary-color: #ff5722;
    --walletup-secondary-color: #333;
    --walletup-success-color: #8bc34a;
    --walletup-error-color: #f44336;
    --walletup-bg-color: #f9f9f9;
    --walletup-border-color: #ddd;
    --walletup-hover-bg: #e1e1e1;
    --walletup-active-bg: #d9d9d9;
    --walletup-animation-duration: 300ms;
}

Integration Examples

Adding Custom Product Limitations

/**
 * Add product-specific quantity limitations
 */
function custom_product_quantity_limits($fields, $quantities, $form_data) {
    // Define product limits
    $product_limits = array(
        12 => array( // Field ID 12
            3 => 2,  // Choice ID 3 limited to 2 items
            5 => 3   // Choice ID 5 limited to 3 items
        ),
        15 => array( // Field ID 15
            1 => 5   // Choice ID 1 limited to 5 items
        )
    );
    
    // Apply limits
    foreach ($quantities as $field_id => $choices) {
        if (isset($product_limits[$field_id])) {
            foreach ($choices as $choice_id => $qty) {
                if (isset($product_limits[$field_id][$choice_id]) && $qty > $product_limits[$field_id][$choice_id]) {
                    $quantities[$field_id][$choice_id] = $product_limits[$field_id][$choice_id];
                }
            }
        }
    }
    
    return $fields;
}
add_filter('walletup_qty_process_quantities', 'custom_product_quantity_limits', 10, 3);

Integrating with External Inventory System

/**
 * Check product inventory before allowing form submission
 */
function check_inventory_before_submit($errors, $form_data) {
    // Only process if no errors yet and we have quantity data
    if (!empty($errors) || empty($_POST['wpforms']['walletup_quantities'])) {
        return $errors;
    }
    
    // Parse quantities data
    $quantities = json_decode(stripslashes($_POST['wpforms']['walletup_quantities']), true);
    if (!$quantities || !is_array($quantities)) {
        return $errors;
    }
    
    // Product ID mapping (WPForms Field ID + Choice ID to product SKU)
    $product_mapping = array(
        '10_2' => 'WIDGET-BASIC',
        '10_3' => 'WIDGET-PREMIUM'
    );
    
    // Check inventory for each product
    foreach ($quantities as $field_id => $choices) {
        foreach ($choices as $choice_id => $qty) {
            $key = $field_id . '_' . $choice_id;
            
            if (isset($product_mapping[$key])) {
                $product_sku = $product_mapping[$key];
                
                // Call external inventory API (example)
                $inventory = my_external_inventory_check($product_sku);
                
                // Add error if requested quantity exceeds inventory
                if ($qty > $inventory) {
                    $errors[$field_id] = sprintf('Sorry, only %d units of this product are available.', $inventory);
                }
            }
        }
    }
    
    return $errors;
}
add_filter('wpforms_process_initial_errors', 'check_inventory_before_submit', 10, 2);

/**
 * Example function to check external inventory
 */
function my_external_inventory_check($sku) {
    // Connect to your inventory API here
    // For this example, we'll return dummy values
    $dummy_inventory = array(
        'WIDGET-BASIC' => 10,
        'WIDGET-PREMIUM' => 5
    );
    
    return isset($dummy_inventory[$sku]) ? $dummy_inventory[$sku] : 0;
}

Compatibility

WordPress Version Compatibility

The plugin is tested and compatible with:

WordPress 5.2 and higher
Latest WordPress version (6.3 at the time of documentation)

WPForms Compatibility

Compatible with:

WPForms 1.7.0 and higher
WPForms Lite and Pro versions

Payment Gateway Compatibility

Works with all WPForms payment addons:

PayPal Commerce
PayPal Standard
Stripe
Square
Authorize.Net
And all other payment gateways supported by WPForms

Browser Compatibility

Tested and compatible with:

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Internet Explorer 11 (basic functionality)

Theme Compatibility

The plugin is designed to work with any properly coded WordPress theme. Specific testing has been performed with:

WordPress default themes (Twenty Twenty, Twenty Twenty-One, etc.)
Popular theme frameworks (GeneratePress, Astra, OceanWP, etc.)
Major page builders (Elementor, Beaver Builder, Divi, etc.)

Plugin Compatibility

Tested with common plugins:

Caching plugins (WP Rocket, W3 Total Cache, etc.)
SEO plugins (Yoast SEO, Rank Math, etc.)
Performance plugins (Perfmatters, Asset CleanUp, etc.)

Localization

Available Translations

The plugin includes:

English (default)
Translation-ready .pot file for creating new translations

Creating Translations

To translate the plugin:

Use a tool like Poedit to open the walletup-wpforms-qty.pot file from the languages directory
Create translations for your language
Save the resulting .po and .mo files in the languages directory using the format walletup-wpforms-qty-{locale}.po (e.g., walletup-wpforms-qty-fr_FR.po)

Translation Strings

Key strings to translate include:

Button labels (increase/decrease)
Error messages
Admin settings labels and descriptions
Accessibility text

Frequently Asked Questions

Does this work with all WPForms payment gateways?

Yes, the plugin works with all WPForms payment gateways including PayPal Commerce, PayPal Standard, Stripe, Square, and Authorize.Net.

Can I customize the appearance of the quantity controls?

Yes! The plugin includes settings to customize colors, animation duration, and more. You can also add custom CSS for further customization.

Is there a maximum quantity limit?

By default, the maximum quantity is set to 99, but you can modify this using the settings page or the walletup_qty_settings filter.

Is the plugin compatible with conditional logic?

Yes, the plugin works seamlessly with WPForms conditional logic. Quantity controls will appear/disappear based on conditional logic rules.

Can I disable quantity controls for specific forms?

Yes, you can use the walletup_qty_disable_controls filter to disable quantity controls for specific forms or on specific pages.

Does this work with multi-page forms?

Yes, the plugin fully supports multi-page forms and maintains quantities when navigating between pages.

Will it work with my theme?

The plugin is designed to work with any well-coded WordPress theme. The quantity controls adapt to your theme’s styling for a seamless experience.

How does this affect my existing forms?

The plugin automatically enhances existing forms with payment checkbox fields without requiring any changes to your form configuration.

Will it slow down my website?

No, the plugin is optimized for performance with features like lazy loading and debounced updates to ensure minimal impact on your site’s speed.

Changelog

1.0.0 (2025-05-09)

Initial release with core functionality
Modern quantity controls for payment checkbox fields
Real-time total updates
Mobile-optimized responsive design
Accessibility features
Settings panel for customization
Developer API with hooks and filters

Support

Getting Help

If you need assistance with the plugin, there are several ways to get help:

Documentation – Refer to this documentation for detailed information
Support Website – Visit walletup.app/support for additional resources
Email Support – Contact [email protected] for direct assistance
WordPress.org – For users who downloaded the plugin from WordPress.org, use the support forums

Reporting Bugs

When reporting bugs, please include:

WordPress version
WPForms version
Plugin version
Description of the issue
Steps to reproduce
Any error messages (from Logs tab if Debug Mode is enabled)
Browser console errors (if applicable)

Feature Requests

We welcome feature requests! Please include:

Clear description of the requested feature
Use case or problem it would solve
Any mock-ups or examples if available

This documentation is maintained by Wallet Up and was last updated on May 9, 2025.

Documentation Overview

Table of Contents

Installation

Requirements

Installation Steps

Getting Started

Quick Start Guide:

Features

Core Features

Accessibility Features

Performance Features

Settings and Configuration

General Settings

Display Settings

Advanced Settings

Integration Settings

Tools

Logs

Usage Guide

Basic Usage

Advanced Usage

Using with Conditional Logic

Using with Multi-page Forms

Use with Product Variations

Troubleshooting

Common Issues

Quantity controls don’t appear

Totals not updating correctly

Style conflicts with theme

Debugging

Developer Documentation

Hooks and Filters

walletup_qty_settings

walletup_qty_disable_controls

walletup_qty_process_quantities

walletup_qty_process_payment

JavaScript API

Initialize Controls Manually

Update Totals Manually

Format Currency

Additional Methods

CSS Customization

Using the Custom CSS Setting

CSS Variables

Integration Examples

Adding Custom Product Limitations

Integrating with External Inventory System

Compatibility

WordPress Version Compatibility

WPForms Compatibility

Payment Gateway Compatibility

Browser Compatibility

Theme Compatibility

Plugin Compatibility

Localization

Available Translations

Creating Translations

Translation Strings

Frequently Asked Questions

Does this work with all WPForms payment gateways?

Can I customize the appearance of the quantity controls?

Is there a maximum quantity limit?

Is the plugin compatible with conditional logic?

Can I disable quantity controls for specific forms?

Does this work with multi-page forms?

Will it work with my theme?

How does this affect my existing forms?

Will it slow down my website?

Changelog

1.0.0 (2025-05-09)

Support

Getting Help

Reporting Bugs

Feature Requests

Please Share This Share this content

You Might Also Like

Efficient MIDI Duration Calculation: Simplify Your Music Projects

The Digital Payment Revolution: How Wallet Up Pro Revolutionizes WordPress with Integrated Payments, QR Codes, and Business Tools

How to customize Order Number in Paid Membership Pro

WalletUP

`walletup_qty_settings`

`walletup_qty_disable_controls`

`walletup_qty_process_quantities`

`walletup_qty_process_payment`

Share this content