Skip to main content

Caching & Performance

Understanding caching, indexing, and performance optimization in the WooCommerce Appointments REST API.

Overview​

The V2 API endpoints leverage a cache/index system for fast reads within a configured horizon. This significantly improves performance for calendar views, dashboards, and slot computations.

How It Works​

Cache/Index System​

  1. Precomputed Index - Availability data is precomputed and stored in a cache table
  2. Cache Horizon - Index is maintained for a configurable time window (typically 90 days)
  3. Automatic Updates - Index is updated when appointments or availability rules change
  4. Fallback - Outside cache horizon or when indexing is disabled, controllers fall back to per-product computation

V2 Endpoints with Caching​

  • Slots (V2) - Uses cached availability when within cache window
  • Index (V2) - Direct read access to precomputed index

V1 Endpoints​

  • No caching - Always compute availability on-demand
  • Use for: One-off queries, testing, or when cache is unavailable

Cache Behavior​

When Cache is Used​

  • Query is within cache horizon (typically 90 days from today)
  • Indexing is enabled in plugin settings
  • Product has availability rules configured

When Fallback is Used​

  • Query is outside cache horizon
  • Indexing is disabled
  • Product has no availability rules
  • Cache table is empty or corrupted

Performance Characteristics​

Index Endpoint​

  • Fastest - Direct database read from index table
  • Use for: Calendar views, dashboards, large time windows
  • Limitation: Only available within cache horizon

Slots V2 Endpoint​

  • Fast - Uses index when available, falls back to computation
  • Use for: Frontend booking forms, availability queries
  • Flexible: Works both within and outside cache window

Slots V1 Endpoint​

  • Slower - Always computes on-demand
  • Use for: Testing, one-off queries, or when V2 is unavailable
  • Reliable: Always works regardless of cache state

Best Practices​

1. Use V2 Endpoints​

Prefer V2 endpoints for production use:

✅ GET /wc-appointments/v2/slots
✅ GET /wc-appointments/v2/index
❌ GET /wc-appointments/v1/slots (use only if V2 unavailable)

2. Query Within Cache Horizon​

For best performance, query dates within the cache horizon:

✅ min_date: today
✅ max_date: today + 90 days
❌ max_date: today + 365 days (outside cache, slower)

3. Use Index for Calendar Views​

For calendar displays, use the Index endpoint:

GET /wc-appointments/v2/index?product_id=123&start_ts=...&end_ts=...

4. Use Slots for Booking Forms​

For booking forms, use the Slots endpoint:

GET /wc-appointments/v2/slots?product_ids=123&min_date=...&max_date=...

5. Cache Client-Side​

Cache API responses client-side to reduce server load:

// Simple client-side cache
const cache = new Map();

async function getCachedSlots(productId, date) {
  const key = `${productId}-${date}`;
  
  if (cache.has(key)) {
    return cache.get(key);
  }
  
  const slots = await fetchSlots(productId, date);
  cache.set(key, slots);
  
  // Clear cache after 5 minutes
  setTimeout(() => cache.delete(key), 5 * 60 * 1000);
  
  return slots;
}

Index Maintenance​

Automatic Updates​

The index is automatically updated when:

  • New appointment is created
  • Appointment is updated or deleted
  • Availability rule is created, updated, or deleted
  • Product availability settings change

Manual Reindexing​

If needed, you can trigger a manual reindex from the admin:

  1. Go to WooCommerce → Appointments → Settings
  2. Navigate to Availability tab
  3. Click Reindex Availability

Cache Invalidation​

Cache is invalidated when:

  • Appointments are created/updated/deleted
  • Availability rules change
  • Product settings change
  • Manual reindex is triggered

Monitoring Performance​

Response Times​

Typical response times:

  • Index endpoint: < 100ms (within cache)
  • Slots V2: < 200ms (within cache), < 500ms (fallback)
  • Slots V1: < 500ms (always computed)

Optimization Tips​

  1. Limit date ranges - Query only the dates you need
  2. Use pagination - For large result sets
  3. Filter efficiently - Use specific product/staff filters
  4. Cache client-side - Reduce API calls
  5. Use Index endpoint - For calendar views within cache horizon

Troubleshooting​

Slow Performance​

Symptoms: API requests taking > 1 second

Possible Causes:

  • Querying outside cache horizon
  • Indexing disabled
  • Large date ranges
  • Many products/staff in query

Solutions:

  1. Check cache horizon settings
  2. Enable indexing if disabled
  3. Reduce date range
  4. Add product/staff filters
  5. Use Index endpoint for calendar views

Missing Data​

Symptoms: Expected slots not appearing

Possible Causes:

  • Index not updated after changes
  • Query outside cache horizon
  • Indexing disabled

Solutions:

  1. Trigger manual reindex
  2. Use V1 endpoint to verify data
  3. Check indexing settings
  4. Verify availability rules are configured