Known Issues & Compatibility

Quick index — jump to the section that matches your symptom. Not listed? Contact support.

Before you begin

How to use this page

1. Start with By symptom below if you have a specific problem
2. Follow the linked section’s steps before changing plugin code
3. Test on staging when disabling plugins or caching

Common first checks

1. ✅ WordPress, WooCommerce, and Appointments are on supported versions — Version requirements
2. ✅ Permalinks are not Plain — REST API
3. ✅ Site timezone and a test booking work — Path 1

By symptom

Symptom / area	Likely cause	Section
Booking form stale or empty slots	Page cache	Caching & Performance
JS errors on booking form	Script minification	Caching & Performance
Date/time picker broken	jQuery UI conflict	JavaScript Conflicts
Form does not submit	JS error or extension	JavaScript Conflicts
Translated emails missing	WPML / Polylang setup	Multilingual
Bundles, composites, or subscriptions	Product type limits	WooCommerce Extensions
Class packs vs subscription credits	Wrong feature enabled	WooCommerce Extensions → Subscriptions
Wrong currency at checkout	Payment / WC extensions	Payment Gateways
Booking form missing in Elementor	Embed method	Page Builders
Blocks not in editor	WooCommerce Blocks version	Page Builders
Admin calendar 403	REST API blocked	REST API
REST API 404	Permalinks or rewrite rules	REST API
Appointments missing on another subsite	Multisite design	Multisite
Reminders not sending	Cron / SMTP	Email Issues
Email templates wrong or missing	Theme overrides	Email Issues
Slow slot loading	Indexing / database	Database & Performance
Indexing fails or stalls	DB permissions / re-index	Database & Performance
Form styling broken	Theme conflict	Theme Compatibility
Admin calendar layout broken	Theme JS/CSS	Theme Compatibility
Nothing above helped	Debug / isolate conflict	General Troubleshooting
Check PHP / WP / WC versions	Requirements	Version Requirements

All sections

Section	What it covers
Caching & Performance Plugins	Page cache, AJAX exclusions, script minification
Multilingual Plugins	WPML, Polylang, translated emails and products
WooCommerce Extensions	Bundles, composites, subscriptions, recurring vs credits
Payment Gateways	WooPayments, Stripe, multi-currency
Page Builders	Elementor, Gutenberg blocks
REST API Issues	Admin calendar 403, endpoint 404, permalinks
Multisite Installations	Per-site appointments, cache prefix
JavaScript Conflicts	Date picker, form submit, browser extensions
Email Issues	Reminders, cron, template overrides
Database & Performance	Slow slots, indexing health
Theme Compatibility	Form CSS, calendar display
General Troubleshooting	Debug mode, safe mode, support ticket
Version Requirements	WordPress, WooCommerce, PHP minimums

---

This page documents known compatibility issues, plugin conflicts, and their solutions.

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

Choosing a model: Which feature do I need? — recurring packages (fixed class pack on an appointable product) vs membership credits (credits per billing period on a subscription product). Both can run on the same store.

How it works:

• ✅ Subscriptions plugin can coexist with Appointments
• ✅ You can sell subscription products that include appointment products as line items
• ✅ A previous issue with manual subscription renewal was fixed in version 4.8.16
• ⚠️ Note: An appointable product cannot be a subscription product (different product types)

Recurring appointment packages (5.4+):

• ✅ Recurring packages on appointable products — customers book a series (RRULE) as prepaid or pay-first
• ✅ Scoped cancel, skip, and reschedule in admin and My Account
• ✅ Pay-first creates a balance order for remaining sessions
• 📖 Recurring appointment packages

Membership credits (5.4+, with WooCommerce Subscriptions):

• ✅ Subscription plans can grant appointment credits per billing period
• ✅ Eligible appointable products; customers book with credits at $0 checkout when a credit applies
• ✅ Credits restore when an appointment is cancelled, subject to plan rules
• 📖 Membership credits

Example use cases:

• Recurring package: "10-session yoga pass" — customer picks weekly slots at checkout; sessions materialize as appointments
• Membership credits: "Monthly membership" grants 4 credits per month toward massage appointments

Notes:

• Appointments are linked via order items, not directly to subscription objects — expected behavior
• Recurring payment (subscription billing) is separate from recurring appointment series (product feature); both can work together with membership credits

Known issues:

None specific to Subscriptions beyond general compatibility. Test deposit + subscription flows on staging.

Payment Gateways

WooCommerce Payments (WooPayments)

Compatibility:

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

Known Issues:

1. Multi-currency in admin panel:
   • 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:

   • Follow the WordPress Cron setup guide
   • Ensure wp-cron.php runs every minute

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

Requirement	Minimum	Recommended
WordPress	5.9+	Latest (tested up to 6.9)
WooCommerce	9.6+	Latest (tested up to 10.6)
PHP	7.4+	8.1 or 8.2
MySQL	5.7+ (or MariaDB 10.3+)	8.0+ (or MariaDB 10.6+)

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