Troubleshooting Decision Tree - Quick Diagnosis Guide

How to Use This Guide

Follow the decision paths below to quickly diagnose and resolve the most common WP-Lister issues. Start with your symptom, answer the questions, and follow the arrows to your solution.

1. Stock/Inventory Sync Issues

Symptom: Stock quantities not updating between WooCommerce and eBay

START: Stock not syncing?
    │
    ▼
Is WP-Lister showing "connected" status?
    │
    ├── NO → Go to Section 2 (Authorization Issues)
    │
    └── YES ▼
            │
        Is "Sync inventory" enabled in your Listing Profile?
            │
            ├── NO → Enable it: Listing Profiles → Edit → Inventory tab → Enable sync
            │
            └── YES ▼
                    │
                Are you using Variable Products?
                    │
                    ├── YES → Check: Is parent OR variation stock managed?
                    │         • Enable "Manage Stock" on variations, not parent
                    │         • Run: WP-Lister → Tools → Update from eBay
                    │
                    └── NO ▼
                            │
                        Check WP-Lister → Log for sync errors
                            │
                            ├── "Token expired" → Re-authorize (Section 2)
                            ├── "SKU not found" → Verify SKU matches in WooCommerce
                            └── No errors? → Run manual sync: Tools → Update eBay

Quick Fix: WP-Lister → Tools → "Update from eBay" forces a full sync

2. eBay Authorization Issues

Symptom: "Token expired", "Auth failed", or connection errors

START: Authorization problems?
    │
    ▼
What error are you seeing?
    │
    ├── "Token expired" or "Auth token is invalid"
    │       │
    │       ▼
    │   Go to WP-Lister → Settings → Accounts
    │       │
    │       ▼
    │   Click "Refresh token" or "Re-authorize"
    │       │
    │       ▼
    │   Complete eBay login flow
    │       │
    │       └── Still failing? → Remove account, add fresh
    │
    ├── "User not found" or "Account suspended"
    │       │
    │       └── Check eBay Seller Hub for account status
    │
    └── Connection timeout / "Could not connect"
            │
            ▼
        Is your site accessible publicly?
            │
            ├── NO → eBay cannot reach local/dev sites
            │        (Use staging with real domain)
            │
            └── YES → Check: Is SSL certificate valid?
                      Check: Any firewall blocking eBay IPs?

Quick Fix: Most auth issues resolve with a fresh re-authorization from Settings → Accounts

3. Listing Errors (Item Specifics / Categories)

Symptom: Listings fail to publish or show validation errors

START: Listing won't publish?
    │
    ▼
Check the error message in WP-Lister → Listings → Status column
    │
    ├── "Item Specifics required" or "Missing required attributes"
    │       │
    │       ▼
    │   Which category are you listing in?
    │       │
    │       ▼
    │   Go to eBay → Sell → Check category requirements
    │       │
    │       ▼
    │   In WP-Lister: Edit listing → Item Specifics tab
    │       │
    │       └── Fill ALL required fields (marked with *)
    │
    ├── "Invalid category" or "Category not found"
    │       │
    │       └── Update categories: WP-Lister → Tools → Update eBay Data
    │
    ├── "Duplicate listing" or "Already listed"
    │       │
    │       └── Check if item exists on eBay already
    │           → Either end existing or link to it
    │
    └── "Title too long" or "Invalid characters"
            │
            └── eBay limit: 80 characters
                Remove special characters: < > @ # $ % etc.

Quick Fix: Most listing errors show exact requirements in the error message - read it carefully!

4. Image Upload Issues

Symptom: Images not appearing on eBay or upload failures

START: Image problems?
    │
    ▼
Are images showing in WooCommerce product?
    │
    ├── NO → Add images to WooCommerce first
    │
    └── YES ▼
            │
        What's the error?
            │
            ├── "Image too large"
            │       │
            │       └── eBay limit: 12MB per image
            │           Recommended: Under 2MB, 1600x1600px
            │
            ├── "Invalid image format"
            │       │
            │       └── Supported: JPG, PNG, GIF
            │           Convert WebP/AVIF to JPG
            │
            ├── "Image URL not accessible"
            │       │
            │       ▼
            │   Is your site publicly accessible?
            │       │
            │       ├── NO → eBay cannot fetch from localhost
            │       │
            │       └── YES → Check image URL directly in browser
            │                 • 404? Image deleted or moved
            │                 • 403? Permission/hotlink issue
            │
            └── Images blurry or cropped on eBay
                    │
                    └── Use square images (1:1 ratio)
                        Minimum 500x500, recommended 1600x1600

Quick Fix: Test image URL directly in browser. If you can't see it, eBay can't either.

5. Business Policies Issues

Symptom: "Business policy required" or shipping/payment/return errors

START: Business Policy errors?
    │
    ▼
Do you have Business Policies enabled on eBay?
    │
    ├── NOT SURE → Check: eBay → Account → Site Preferences
    │              → Shipping preferences → Opt in
    │
    ├── NO → You need these for WP-Lister 4.0
    │        Enable them in eBay Seller Hub first
    │
    └── YES ▼
            │
        Are policies showing in WP-Lister?
            │
            ├── NO → WP-Lister → Tools → "Refresh Business Policies"
            │
            └── YES ▼
                    │
                What's the specific error?
                    │
                    ├── "Payment policy required"
                    │       │
                    │       └── Create payment policy in eBay (eBay now manages payments)
                    │
                    ├── "Shipping policy required"
                    │       │
                    │       └── Edit Listing Profile → Select a shipping policy
                    │
                    ├── "Return policy required"
                    │       │
                    │       └── Edit Listing Profile → Select a return policy
                    │
                    └── "Policy not found" after it was working
                            │
                            └── Policy may have been deleted on eBay
                                Create new one, refresh, re-assign

Quick Fix: After any policy changes on eBay, always run "Refresh Business Policies" in WP-Lister

Still Stuck?

If you've followed the decision tree and still have issues:

1. Check the Log: WP-Lister → Log shows detailed error messages
2. Update Plugin: Ensure you're on the latest WP-Lister version
3. Clear Cache: If using caching plugins, clear and test
4. Contact Support: Include your log entries and screenshots

When contacting support, please provide:

• WP-Lister version number
• WordPress version
• The exact error message
• Screenshot of the issue
• Recent entries from WP-Lister → Log