Skip to main content

WordPress Plugin Troubleshooting

Common issues and solutions for the Loyalteez WordPress plugin integration.

Installation Issues​

Plugin Not Installing​

Symptoms:

  • Plugin installation fails
  • "Plugin file not found" error
  • Activation errors

Solutions:

1. Check PHP Version:

  • Minimum PHP 7.4 required
  • Check: WordPress Admin → Tools → Site Health → Info → Server
  • Upgrade PHP if needed

2. Check WordPress Version:

  • Minimum WordPress 5.0 required
  • Update WordPress if needed

3. Check File Permissions:

  • wp-content/plugins/ must be writable
  • Verify plugin files uploaded correctly
  • Check file permissions: 755 for directories, 644 for files

4. Manual Installation:

  • Download plugin ZIP file
  • Upload via WordPress Admin → Plugins → Add New → Upload Plugin
  • Activate plugin

Plugin Not Activating​

Symptoms:

  • Plugin appears but won't activate
  • Fatal error on activation
  • White screen after activation

Solutions:

1. Check Error Logs:

  • Check WordPress debug log: wp-content/debug.log
  • Enable WP_DEBUG: define('WP_DEBUG', true); in wp-config.php
  • Check PHP error logs

2. Check Plugin Conflicts:

  • Deactivate other plugins
  • Try activating Loyalteez plugin
  • Reactivate other plugins one by one

3. Check Theme Compatibility:

  • Switch to default theme (Twenty Twenty-Three)
  • Try activating plugin
  • Switch back to your theme

4. Check PHP Memory Limit:

  • Minimum 128MB recommended
  • Increase: define('WP_MEMORY_LIMIT', '256M'); in wp-config.php

Configuration Issues​

Brand ID Not Saving​

Symptoms:

  • Brand ID field doesn't save
  • Settings page shows error
  • Configuration resets

Solutions:

1. Check User Permissions:

  • User must have manage_options capability (Administrator)
  • Verify user role has correct permissions

2. Check Database Connection:

  • Verify WordPress database is accessible
  • Check wp_options table exists
  • Verify database user has write permissions

3. Check for Plugin Conflicts:

  • Security plugins may block option saves
  • Check security plugin settings
  • Whitelist Loyalteez plugin

4. Clear Cache:

  • Clear WordPress cache (if using caching plugin)
  • Clear browser cache
  • Try saving again

API URL Not Working​

Symptoms:

  • API connection test fails
  • Events not tracking
  • 403/401 errors

Solutions:

1. Verify API URL:

  • Default: https://api.loyalteez.app
  • Must use HTTPS (not HTTP)
  • Verify URL is accessible: curl https://api.loyalteez.app/health

2. Check Domain Authentication:

  • Domain must be authenticated in Partner Portal
  • Navigate to Partner Portal → Integrations → WordPress
  • Add your domain: https://yoursite.com

3. Check SSL Certificate:

  • Site must use HTTPS
  • SSL certificate must be valid
  • Mixed content warnings may cause issues

4. Test API Connection:

  • Use "Test API Connection" button in plugin settings
  • Check response for error messages
  • Verify Brand ID is correct

Event Tracking Issues​

Events Not Triggering​

Symptoms:

  • Events configured but not tracking
  • No events in Partner Portal analytics
  • No LTZ rewards distributed

Solutions:

1. Check Event Configuration:

  • Verify events are enabled in plugin settings
  • Check WordPress hook names are correct
  • Verify event names match Partner Portal

2. Check Hook Names:

  • Common hooks: comment_post, user_register, init
  • Verify hook is triggered (add logging)
  • Check hook priority (default: 10)

3. Check User Email:

  • Events require user email
  • Verify user is logged in (for user events)
  • Check email format is valid

4. Check API Connection:

  • Verify API URL is accessible
  • Check API response codes
  • Review WordPress error logs

5. Enable Debug Mode:

  • Enable debug logging in plugin settings
  • Check wp-content/debug.log
  • Review API request/response logs

Events Tracking But No Rewards​

Symptoms:

  • Events appear in Partner Portal analytics
  • No LTZ rewards distributed
  • Wallet balance not increasing

Solutions:

1. Check Automation Status:

  • Verify automation is enabled in Partner Portal
  • Navigate to Partner Portal → Automation
  • Toggle "Enable Automation" if disabled

2. Check Event Configuration:

  • Verify event has reward configured
  • Check reward amount is set
  • Verify event is active

3. Check Cooldown Periods:

  • User may be on cooldown
  • Check cooldown settings in Partner Portal
  • Verify event hasn't been rewarded recently

4. Check Rate Limits:

  • User may have hit rate limit
  • Check rate limit settings
  • Wait for cooldown period

"API returns 403 Forbidden"​

Symptoms:

  • Events fail with 403 error
  • "Automation disabled" message
  • Connection test fails

Solutions:

1. Check Automation Status:

  • Enable automation in Partner Portal
  • Navigate to Partner Portal → Automation
  • Toggle "Enable Automation" to ON

2. Check Domain Authentication:

  • Domain must be authenticated
  • Verify domain in Partner Portal
  • Domain must match exactly (including https://)

3. Check Brand ID:

  • Verify Brand ID is correct
  • Brand ID must match Partner Portal account
  • Check for typos or extra spaces

4. Check API Key:

  • API uses domain authentication (not keys)
  • Verify domain is listed in Partner Portal
  • Check domain format: https://yoursite.com

"API returns 400 Bad Request"​

Symptoms:

  • Events fail with 400 error
  • "Invalid event data" message
  • Missing required fields

Solutions:

1. Check Event Data:

  • Verify all required fields are present
  • Required: brandId, eventType, userEmail
  • Check event data format

2. Check Event Type:

  • Event type must match Partner Portal
  • Verify event name spelling
  • Check event is configured in Partner Portal

3. Check User Email:

  • Email must be valid format
  • User must be logged in (for user events)
  • Check email is not empty

4. Enable Debug Mode:

  • Check debug logs for request data
  • Review API request body
  • Verify data format matches API requirements

Shortcode Issues​

Shortcodes Not Displaying​

Symptoms:

  • Shortcodes show as plain text
  • No output from shortcode
  • Error messages instead of content

Solutions:

1. Check Plugin Activation:

  • Plugin must be activated
  • Verify in WordPress Admin → Plugins
  • Try deactivating and reactivating

2. Check User Login:

  • Some shortcodes require login
  • Verify user is logged in
  • Check shortcode login requirements

3. Check Configuration:

  • Brand ID must be configured
  • Verify plugin settings are saved
  • Check for configuration errors

4. Check PHP Errors:

  • Enable WP_DEBUG
  • Check wp-content/debug.log
  • Review PHP error messages

Dashboard Not Loading​

Symptoms:

  • Dashboard shortcode shows "Loading..."
  • JavaScript errors in console
  • Dashboard tabs not working

Solutions:

1. Check JavaScript:

  • Verify JavaScript files are loaded
  • Check browser console for errors
  • Disable JavaScript minification plugins

2. Check API Endpoints:

  • Verify REST API endpoints are accessible
  • Test: /wp-json/loyalteez/v1/leaderboard
  • Check REST API is enabled

3. Check Nonce:

  • Verify nonce is generated correctly
  • Check wp_create_nonce('wp_rest')
  • Clear cache and try again

4. Check jQuery:

  • jQuery must be loaded
  • Verify jQuery dependency is met
  • Check for jQuery conflicts

Balance Not Loading​

Symptoms:

  • Balance shows "Loading..." forever
  • Balance shows 0 or error
  • Balance not updating

Solutions:

1. Check User Login:

  • User must be logged in
  • Verify user session is active
  • Check login cookie

2. Check API Connection:

  • Verify API URL is accessible
  • Check API response
  • Review browser console for errors

3. Check Wallet Creation:

  • Wallet is created on first reward
  • User must earn LTZ first
  • Check Partner Portal for user activity

4. Check JavaScript Errors:

  • Review browser console
  • Check for API errors
  • Verify JavaScript files are loaded

Leaderboard Empty​

Symptoms:

  • Leaderboard shows no entries
  • "No data" message
  • Error loading leaderboard

Solutions:

1. Check Data Availability:

  • Verify users have earned LTZ
  • Check Partner Portal analytics
  • Ensure activity exists for selected period

2. Check Filters:

  • Try different metric: ltz_earned, activity, streak
  • Try different period: week, month, all
  • Check filter parameters are valid

3. Check API Response:

  • Verify REST API endpoint is working
  • Test: /wp-json/loyalteez/v1/leaderboard?metric=ltz_earned&period=all
  • Check API response format

4. Check Shared Services:

  • Verify shared services URL is correct
  • Check shared services API status
  • Review API logs

REST API Issues​

API Endpoints Not Working​

Symptoms:

  • REST API endpoints return 404
  • Endpoints not accessible
  • Authentication errors

Solutions:

1. Check REST API:

  • Verify WordPress REST API is enabled
  • Test: /wp-json/
  • Check for REST API conflicts

2. Check Permalinks:

  • Permalinks must not be "Plain"
  • Settings → Permalinks → Post name (recommended)
  • Flush permalinks: Settings → Permalinks → Save Changes

3. Check Authentication:

  • Verify nonce is included in requests
  • Check X-WP-Nonce header
  • Verify user is logged in (for authenticated endpoints)

4. Check URL Rewrites:

  • Verify .htaccess is writable
  • Regenerate permalink structure
  • Check web server rewrite rules

Check-in Not Working​

Symptoms:

  • Check-in button doesn't work
  • Error when checking in
  • Streak not updating

Solutions:

1. Check User Login:

  • User must be logged in
  • Verify user session
  • Check login cookie

2. Check Nonce:

  • Verify nonce is included
  • Check nonce generation
  • Clear cache and regenerate

3. Check Shared Services:

  • Verify shared services URL
  • Check shared services API status
  • Review API response

4. Check Error Messages:

  • Review browser console
  • Check API response
  • Review WordPress error logs

Perk Redemption Fails​

Symptoms:

  • Perk redemption button doesn't work
  • Error when redeeming
  • Transaction fails

Solutions:

1. Check User Balance:

  • Verify user has sufficient LTZ
  • Check balance is displayed correctly
  • Verify balance is current

2. Check Perk Availability:

  • Verify perk is available
  • Check perk supply limits
  • Verify perk is active

3. Check API Connection:

  • Verify shared services API
  • Check redemption endpoint
  • Review API response

4. Check Error Messages:

  • Review browser console
  • Check API error response
  • Verify error message details

Performance Issues​

Plugin Slowing Down Site​

Symptoms:

  • Site loads slowly
  • Page generation time increased
  • Database queries slow

Solutions:

1. Check Hook Usage:

  • Avoid using init hook (runs on every page load)
  • Use specific hooks instead
  • Optimize hook callbacks

2. Check Database Queries:

  • Enable query logging
  • Review database query performance
  • Add indexes if needed

3. Check API Calls:

  • API calls are asynchronous
  • Verify API timeouts are reasonable
  • Use caching where appropriate

4. Check Caching:

  • Use caching plugin
  • Cache API responses
  • Optimize asset loading

Compatibility Issues​

Theme Conflicts​

Symptoms:

  • Shortcodes not styled correctly
  • Dashboard layout broken
  • CSS conflicts

Solutions:

1. Check Theme CSS:

  • Review theme CSS for conflicts
  • Use browser inspector to identify conflicts
  • Add custom CSS to override

2. Custom Styling:

  • Add custom CSS in theme
  • Use WordPress Customizer → Additional CSS
  • Target plugin classes specifically

3. Check Theme Template:

  • Verify theme supports shortcodes
  • Check theme template files
  • Test with default theme

Plugin Conflicts​

Symptoms:

  • Plugin features not working
  • Errors when other plugins active
  • Conflicts with specific plugins

Solutions:

1. Identify Conflicting Plugin:

  • Deactivate all other plugins
  • Activate plugins one by one
  • Test after each activation

2. Check Security Plugins:

  • Security plugins may block API calls
  • Whitelist Loyalteez API URLs
  • Check firewall rules

3. Check Caching Plugins:

  • Caching may cache API responses
  • Exclude API endpoints from cache
  • Clear cache after configuration changes

Debugging Tips​

Enable Debug Mode​

Add to wp-config.php:

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

Check logs: wp-content/debug.log

Check REST API​

Test REST API base:

https://yoursite.com/wp-json/

Test Loyalteez endpoints:

https://yoursite.com/wp-json/loyalteez/v1/leaderboard

Review Browser Console​

  • Open browser developer tools (F12)
  • Check Console tab for errors
  • Review Network tab for API requests

Check Database​

Check plugin options:

SELECT * FROM wp_options WHERE option_name LIKE 'loyalteez%';

Getting Help​

If you're still experiencing issues:

  1. Check Documentation:

  2. Review Logs:

    • WordPress debug log: wp-content/debug.log
    • PHP error logs
    • Browser console errors

  3. Contact Support:

    • Email: [email protected]
    • Include: Error messages, logs, WordPress version, PHP version, plugin version

Need help? [email protected]

Last updated on