Skip to main content

Known Issues & Compatibility

This page documents known compatibility issues, plugin conflicts, and their solutions. If you encounter an issue not listed here, please contact support.

Caching & Performance Plugins​

Issue: Booking form not loading or showing incorrect availability​

Affected Plugins:

  • WP Rocket
  • W3 Total Cache
  • WP Super Cache
  • Autoptimize
  • WP Optimize
  • Any page caching plugin

Problem: Caching plugins can cache the booking form, causing availability slots to be outdated or preventing real-time availability checks.

Solution:

  1. Exclude appointment products from caching:

    • In your caching plugin settings, add appointment product pages to the exclusion list
    • Example URLs to exclude: /product/* (where * is your appointment product slug)

  2. Exclude AJAX requests:

    • Exclude /wp-admin/admin-ajax.php from caching
    • Exclude /wp-json/wc-appointments/* API endpoints

  3. Disable object caching for appointments:

    • If using Redis/Memcached, exclude appointment-related database queries

  4. Clear cache after changes:

    • Always clear all caches after creating or editing appointments, availability rules, or products

Issue: JavaScript errors in booking form​

Affected Plugins:

  • Autoptimize
  • WP Rocket (JavaScript minification)
  • Any JavaScript minification/optimization plugin

Problem: JavaScript minification can break the appointment booking form functionality, causing errors like "Cannot read property of undefined" or form not submitting.

Solution:

  1. Exclude appointment scripts from minification:

    • Add these files to exclusion list:
      • wc-appointments-appointment-form*
      • wc-appointments-date-picker*
      • wc-appointments-time-picker*
      • wc-appointments-staff-picker*
      • wc-appointments-month-picker*

  2. Disable JavaScript aggregation:

    • For appointment product pages, disable JavaScript aggregation/concatenation

  3. Test in safe mode:

    • Temporarily disable the optimization plugin to confirm it's the cause

Multilingual Plugins​

WPML (WooCommerce Multilingual)​

Compatibility:

  • ✅ Fully compatible with proper setup
  • Requires: WPML Multilingual CMS 4.6.15+ and WooCommerce Multilingual 5.4.0+

Known Issues:

  1. Appointment emails not translated:

    • Solution: Ensure email templates are translated in WPML String Translation
    • Translate strings under "WooCommerce Appointments" domain

  2. Availability rules not syncing across languages:

    • Solution: Availability rules are global by design. Use language-specific products if needed

  3. Staff assignments not translating:

    • Solution: Staff members are global. Create language-specific staff if needed

Polylang for WooCommerce​

Compatibility:

  • ✅ Fully compatible
  • Requires: Polylang for WooCommerce 2.1.4+

Known Issues:

  1. Appointment status translations:

    • Solution: Translate appointment statuses in Polylang string translations
    • Look for "WooCommerce Appointments" domain

  2. Product translations:

    • Solution: Ensure appointment products are properly linked as translations in Polylang

WooCommerce Extensions​

Understanding Compatibility​

Important: Appointments is a product type (like 'simple', 'variable', etc.). In WooCommerce, a product can only be one product type at a time. This means:

  • An appointment product cannot also be a bundle, composite, or subscription product
  • However, appointment products can be used as items within bundles and composites
  • These plugins are "compatible" because they can coexist and work together, not because they integrate directly

WooCommerce Product Bundles​

How it works:

  • ✅ Product Bundles can contain appointment products as bundled items
  • ✅ You can create a bundle that includes appointment products along with other products
  • ⚠️ Note: If using Product Add-ons (bundled with Appointments), Product Bundles version 8.1.0+ is required for Product Add-ons compatibility

Example Use Case: Create a bundle like "Massage Package" that includes:

  • 1x Appointment product (60-minute massage)
  • 1x Simple product (massage oil)
  • 1x Simple product (gift certificate)

Known Issues:

None reported. Appointment products work as bundled items. If you're using Product Add-ons with Bundles, ensure Product Bundles is version 8.1.0 or higher.

WooCommerce Composite Products​

How it works:

  • ✅ Composite Products can contain appointment products as composited items
  • ✅ You can create a composite product where customers choose appointment products as options
  • ⚠️ Note: If using Product Add-ons (bundled with Appointments), Composite Products version 10.1.0+ is required for Product Add-ons compatibility

Example Use Case: Create a composite like "Spa Day Package" where customers choose:

  • Appointment product: Choose massage time (30/60/90 minutes)
  • Appointment product: Choose facial treatment type
  • Simple product: Choose lunch option

Known Issues:

None reported. Appointment products work as composited items. If you're using Product Add-ons with Composite Products, ensure Composite Products is version 10.1.0 or higher.

WooCommerce Subscriptions​

How it works:

  • ✅ Subscriptions plugin can coexist with Appointments
  • ✅ You can create subscription products that include appointment products
  • ✅ A previous issue with manual subscription renewal was fixed in version 4.8.16
  • ⚠️ Note: An appointment product cannot BE a subscription product (they're different product types)

Example Use Case:

  • Create a subscription product: "Monthly Gym Membership"
  • Include appointment products as subscription items: "Personal Training Session" (booked monthly)
  • Customers get recurring access to book appointments as part of their subscription

Known Issues:

  1. Appointments not directly linked to subscriptions:

    • Note: Appointments are linked via order items, not directly to subscriptions
    • This is expected behavior - appointments are created from order items, not subscription objects

  2. Recurring appointment bookings:

    • Note: Appointments plugin doesn't support automatic recurring bookings natively
    • Each appointment must be booked individually, even if part of a subscription
    • Use subscription renewals to create new order items, then customers can book new appointments from those orders

Payment Gateways​

WooCommerce Payments (WooPayments)​

Compatibility:

  • ✅ Fully compatible
  • Multi-currency is supported in admin appointment creation

Known Issues:

  1. Multi-currency in admin modal:
    • Solution: Ensure WooPayments multi-currency is properly configured
    • Currency conversion happens automatically in admin appointment creation

Stripe​

Compatibility:

  • ✅ Fully compatible

Known Issues:

None reported. If you encounter issues, ensure both plugins are up to date.

Page Builders​

Elementor​

Compatibility:

  • ✅ Compatible with shortcodes and blocks

Known Issues:

  1. Booking form not displaying:

    • Solution: Use the Appointment Form block or shortcode within Elementor
    • Don't try to embed the product page directly

  2. Styling conflicts:

    • Solution: Use Elementor's custom CSS to override appointment form styles if needed
    • Check for CSS specificity conflicts

Gutenberg / Block Editor​

Compatibility:

  • ✅ Fully compatible
  • Native blocks available: Appointment Form, Availability Filter

Known Issues:

  1. Blocks not appearing:
    • Solution: Ensure WooCommerce Blocks 7.2.0+ is installed and active
    • Clear browser cache and WordPress cache

REST API Issues​

Issue: Admin calendar not loading (403 error)​

Problem: WordPress REST API is disabled or restricted, preventing the admin calendar from loading.

Solution:

  1. Enable REST API:

    • Ensure REST API is not disabled in wp-config.php
    • Remove any code that disables REST API

  2. Check permissions:

    • Ensure admin users have proper capabilities
    • Check if security plugins are blocking REST API

  3. Check .htaccess:

    • Ensure .htaccess doesn't block /wp-json/ requests

Issue: API endpoints returning 404​

Problem: Permalink structure not set or REST API routes not registered.

Solution:

  1. Set permalink structure:

    • Go to Settings → Permalinks
    • Choose any structure other than "Plain"
    • Save (no need to change, just save)

  2. Flush rewrite rules:

    • Deactivate and reactivate WooCommerce Appointments
    • Or run: flush_rewrite_rules() via WP-CLI

Multisite Installations​

Issue: Appointments not syncing across sites​

Problem: In WordPress Multisite, appointments are site-specific by design.

Solution:

  • This is expected behavior
  • Each site in the network has its own appointments
  • Use network admin to manage appointments across sites if needed

Issue: Availability cache issues on multisite​

Problem: Cache table prefix may be incorrect for sub-sites.

Solution:

  1. Check table prefix:

    • Ensure database tables use correct site-specific prefix
    • Run the indexing health check: Appointments → Settings → Indexing

  2. Re-index if needed:

    • Go to Appointments → Settings → Indexing
    • Click "Re-index All" if issues persist

JavaScript Conflicts​

Issue: Date/time picker not working​

Affected:

  • Themes with conflicting jQuery UI versions
  • Plugins that load outdated jQuery UI

Solution:

  1. Check jQuery UI version:

    • Appointments requires jQuery UI 1.12.1+
    • Use browser console to check for jQuery UI errors

  2. Disable conflicting scripts:

    • Temporarily deactivate other plugins to identify the conflict
    • Contact the conflicting plugin's developer

  3. Use compatibility mode:

    • Some themes have "jQuery compatibility mode" - enable it

Issue: Form submission not working​

Problem: JavaScript errors preventing form submission.

Solution:

  1. Check browser console:

    • Open browser developer tools (F12)
    • Look for JavaScript errors
    • Share errors with support

  2. Disable browser extensions:

    • Some ad blockers or privacy extensions can interfere
    • Test in incognito/private mode

  3. Check for PHP errors:

    • Enable WordPress debug mode
    • Check error logs for PHP fatal errors

Email Issues​

Issue: Reminder emails not sending​

Problem: WordPress cron not running (see WordPress Cron tutorial).

Solution:

  1. Set up real cron job:

  2. Check email settings:

    • Verify reminder emails are enabled in WooCommerce → Settings → Emails
    • Check spam folder

  3. Test email delivery:

    • Use a plugin like "WP Mail SMTP" to test email delivery
    • Check server mail logs

Issue: Email templates not loading​

Problem: Theme override templates are outdated or missing.

Solution:

  1. Check template location:

    • Templates should be in: yourtheme/woocommerce/appointments/emails/
    • Ensure all required template files exist

  2. Update templates:

    • Compare your theme templates with plugin templates
    • Update any outdated template files

Database & Performance​

Issue: Slow booking form loading​

Problem: Large number of appointments or complex availability rules.

Solution:

  1. Enable indexing:

    • Go to Appointments → Settings → Indexing
    • Enable "Use Indexed Availability Checking"
    • Set appropriate cache horizon (3-6 months recommended)

  2. Optimize database:

    • Run database optimization
    • Clean up old appointments if not needed

  3. Check server resources:

    • Ensure adequate PHP memory limit (256MB+)
    • Check server response times

Issue: Indexing not working​

Problem: Database permissions or table creation issues.

Solution:

  1. Check database permissions:

    • Ensure WordPress database user can CREATE tables
    • Check for disk space issues

  2. Manual re-index:

    • Go to Appointments → Settings → Indexing
    • Click "Re-index All"
    • Monitor for errors

  3. Check health:

    • Use the indexing health check tool
    • Review any reported issues

Theme Compatibility​

Issue: Booking form styling broken​

Problem: Theme CSS conflicts with appointment form styles.

Solution:

  1. Check theme compatibility:

    • Test with default WordPress theme (Twenty Twenty-Four)
    • If it works, the issue is theme-specific

  2. Add custom CSS:

    • Use theme's custom CSS option
    • Override conflicting styles with higher specificity

  3. Contact theme developer:

    • Report the conflict to your theme developer
    • Request compatibility update

Issue: Calendar not displaying correctly​

Problem: Theme JavaScript or CSS conflicts.

Solution:

  1. Disable theme scripts:

    • Temporarily switch to default theme to confirm
    • Contact theme developer if confirmed

  2. Check for jQuery conflicts:

    • Ensure theme uses compatible jQuery version
    • Some themes load outdated jQuery

General Troubleshooting​

Still having issues?​

  1. Enable debug mode:

    define('WP_DEBUG', true);
    define('WP_DEBUG_LOG', true);
    define('WP_DEBUG_DISPLAY', false);

  2. Check error logs:

    • Review wp-content/debug.log
    • Check server error logs

  3. Test in safe mode:

    • Deactivate all plugins except WooCommerce and Appointments
    • Switch to default theme
    • If it works, reactivate plugins one by one to find the conflict

  4. Contact support:

    • Submit a support ticket
    • Include error logs, PHP version, WordPress version, and plugin versions
    • Describe steps to reproduce the issue

Version Requirements​

Minimum Requirements:

  • WordPress: 6.0+
  • WooCommerce: 8.0+
  • PHP: 7.4+ (8.0+ recommended)
  • MySQL: 5.7+ or MariaDB 10.3+

Recommended:

  • WordPress: Latest version
  • WooCommerce: Latest version
  • PHP: 8.1 or 8.2
  • MySQL: 8.0+ or MariaDB 10.6+

Always keep WordPress, WooCommerce, and all plugins updated to the latest versions for best compatibility and security.