Product Sync Issues

Symptoms

• New products don’t appear on your WordPress® site
• Product updates (price, stock, title) not reflected
• Product sync showing as “failed” in admin
• Admin notice: “Webhook delivery issues detected”

Common Causes

1. Webhook Connectivity Issues

• BigCommerce webhooks not reaching your WordPress® site
• Firewall or security plugin blocking webhook requests
• SSL certificate problems preventing HTTPS webhooks

2. Resource Limits Exceeded

• PHP memory limit too low for large product catalogs
• Execution timeout during sync operations
• Cron job overlap causing processing conflicts

3. API Failures

• BigCommerce API rate limiting
• Authentication token expired
• Temporary BigCommerce API outage

Solutions

Check Webhook Health Status

1. Navigate to Commerce Connect settings in WordPress® admin
2. Look for webhook health notice - A yellow warning banner indicates detected issues
3. Review error messages for specific failure details

Verify Webhook Connectivity

Check if webhooks can reach your site:

# Test webhook endpoint accessibility
curl -I https://yoursite.com/wp-json/commerce-connect/v1/webhooks

Expected response: 200 OK or 401 Unauthorized (both mean endpoint is reachable)

If you get connection errors:

• Check firewall rules - Allow webhook requests from BigCommerce IP ranges
• Verify SSL certificate - Webhooks require valid HTTPS
• Check security plugins - Temporarily disable to test if blocking webhooks

Fix Resource Limit Issues

If sync stops partway through processing:

1. Increase PHP memory limit in wp-config.php:

   define('WP_MEMORY_LIMIT', '512M');
   define('WP_MAX_MEMORY_LIMIT', '512M');

2. Increase execution time in wp-config.php:

   set_time_limit(300); // 5 minutes

3. Verify cron is running:

   wp cron event list

   Look for commerce_connect_sync_products scheduled every minute

Force Manual Resync

To trigger immediate product sync:

1. Go to Commerce Connect → Settings → Advanced
2. Click “Sync Products Now” button
3. Monitor progress in the admin notice area
4. Check logs for any error messages

Clear Backoff State

If sync is stuck in exponential backoff after failures:

1. Navigate to WP-CLI or WordPress® admin

2. Delete the backoff option:

   wp option delete commerce_connect_sync_backoff

3. Manually trigger sync to restart

Debug Webhook Deliveries

Check webhook event history in BigCommerce:

1. Log into BigCommerce admin
2. Go to Settings → Webhooks
3. Click on your webhook to view delivery history
4. Review failed deliveries for error codes and responses

Common error codes:

• 401 Unauthorized - Authentication failure, regenerate webhook secret
• 404 Not Found - Webhook URL incorrect, verify endpoint
• 500 Server Error - WordPress® error, check error logs
• Timeout - Site too slow to respond, check resource limits

Verification

After applying fixes, verify sync is working:

1. Edit a test product in BigCommerce (change title or price)

2. Wait 1-2 minutes for webhook processing

3. Check product on WordPress® site - changes should appear

4. Review webhook health status - should show no errors

5. Check Action Scheduler for successful processing:

   wp action-scheduler list --hook=commerce_connect_process_webhook --status=complete

Prevention

Monitor Webhook Health

The plugin runs daily health checks automatically. To stay informed:

1. Enable email notifications for failed webhooks (if supported)
2. Check admin dashboard weekly for health warnings
3. Monitor Action Scheduler for recurring failures

Optimize Resource Configuration

For large catalogs (1,000+ products):

1. Set adequate memory limits (512MB minimum)
2. Use dedicated hosting with sufficient resources
3. Consider increasing cron frequency only if needed
4. Monitor server resource usage during sync operations

Maintain BigCommerce Connection

1. Keep authentication tokens fresh - plugin handles this automatically
2. Monitor BigCommerce API status at status.bigcommerce.com
3. Test webhooks after platform changes (firewall, hosting, SSL)

Advanced Debugging

View Sync Logs

Check WordPress® error logs for detailed sync information:

# View most recent sync events
tail -f wp-content/debug.log | grep "commerce_connect"

Look for:

• Product sync backing off due to resource limits - Resource pressure
• Webhook health check found issues - Connection problems
• Products sync failed - API or processing errors

Resource Monitoring

The plugin tracks resource usage during sync. High memory/time ratios indicate:

• 85%+ memory usage - Increase memory limit
• 85%+ execution time - Increase timeout or reduce batch size
• Cron overlap warnings - Sync taking longer than 1 minute interval

Webhook Retry Logic

Failed webhooks automatically retry with exponential backoff:

Attempt	Delay	Total Time Since Failure
1st retry	1 minute	1 minute
2nd retry	5 minutes	6 minutes
3rd retry	15 minutes	21 minutes
4th retry	30 minutes	51 minutes
5th retry	1 hour	~2 hours

After 5 failed attempts, the webhook event is permanently dropped and requires manual intervention.