Troubleshooting

Symptoms: Blank screen, loading spinner that never completes, or JavaScript errors.

Possible Causes & Solutions:

1. JavaScript Errors:
   • Check your browser's console for error messages
   • Ensure you've properly included the Refgrow script in your HTML
   • Verify that you haven't added custom JavaScript that conflicts with the dashboard
2. Content Security Policy (CSP) Blocking:
   • If you have a strict CSP, add *.refgrow.com to your script-src and connect-src directives
3. Network Issues:
   • Verify your internet connection
   • Check if your firewall or proxy is blocking connections to Refgrow domains
4. Incorrect Installation:
   • Review the installation guide to ensure you've correctly implemented the dashboard
   • Verify your program ID is correct in the dashboard element attributes

Symptoms: Dashboard appears unstyled, misaligned elements, or conflicting styles.

Possible Causes & Solutions:

1. CSS Conflicts:
   • Check if your website's CSS is overriding Refgrow's styles
   • Try adding the dashboard in an isolated container with minimal styling
2. Missing CSS Resources:
   • Verify that your CSP doesn't block stylesheets from Refgrow domains
3. Responsive Layout Issues:
   • Ensure the container for the dashboard is wide enough
   • Check that you haven't applied CSS that affects the dashboard's responsive behavior

Symptoms: Unable to log in, constant redirects, or "unauthorized" errors.

Possible Causes & Solutions:

1. JWT Token Issues:
   • Verify your JWT is properly signed with the correct secret
   • Check that the token hasn't expired
   • Ensure all required claims are included in the token
2. Cookie Issues:
   • Ensure cookies are enabled in the user's browser
   • Check for any third-party cookie blocking that might affect authentication
3. Cross-Origin Problems:
   • If you're using a custom authentication endpoint, verify your CORS headers are properly set

Symptoms: Clicks or visits not appearing in analytics, zero referral data.

Possible Causes & Solutions:

1. Tracking Script Not Installed:
   • Verify you've added the Refgrow tracking script to all pages of your website
   • Check that the script is loading properly (no 404 errors)
2. Ad Blockers or Privacy Tools:
   • Some users' ad blockers might prevent tracking
   • Consider adding a message asking users to disable ad blockers for your site
3. Incorrect Referral Links:
   • Check that affiliates are using the correct referral links with proper parameters
   • Verify the referral parameter name matches what your tracking script expects
4. Improper URL Structure:
   • Ensure your website properly preserves URL parameters across redirects
   • Verify that your server-side routing doesn't strip query parameters

Symptoms: Clicks are tracked but conversions (purchases, sign-ups) don't appear.

Possible Causes & Solutions:

1. Missing Conversion Tracking:
   • Verify you've implemented the conversion tracking script on your thank-you/confirmation pages
   • Check that you're calling the conversion tracking function with the correct parameters
2. Cookie Issues:
   • Ensure your website properly stores and retrieves the referral cookies
   • Check if users are clearing cookies between visits
3. Integration Problems:
   • If using Stripe or other platform integrations, verify your webhooks are configured correctly
   • Check that your API keys and credentials are valid
4. Fraud Prevention Blocking:
   • Refgrow has fraud detection that might flag suspicious conversions
   • Check your program settings for any strict fraud filters

Symptoms: Discrepancies between your internal data and Refgrow's reports.

Possible Causes & Solutions:

1. Attribution Window Settings:
   • Check your attribution window settings in program configuration
   • Understand how the attribution model works (first-click, last-click, etc.)
2. Duplicate Transactions:
   • Ensure your conversion tracking isn't firing multiple times for the same transaction
   • Implement deduplication logic if necessary
3. Data Processing Delay:
   • Allow 24 hours for all data to be processed and aggregated in reports
4. Timezone Differences:
   • Verify your program's timezone setting matches your expected reporting timezone

Symptoms: Stripe payments not triggering commissions, webhook errors.

Possible Causes & Solutions:

1. Webhook Configuration:
   • Verify your Stripe webhook is set up correctly with the right events
   • Check that the webhook secret is properly configured in Refgrow
2. API Key Issues:
   • Ensure you're using a live API key in production (not test mode)
   • Verify the API key has sufficient permissions for webhook operations
3. Product Mapping:
   • Check that your Stripe products are properly mapped to commission structures in Refgrow
4. Webhook Deliverability:
   • Check Stripe dashboard for failed webhook attempts
   • Ensure your firewall isn't blocking incoming webhook requests

For more details, see the Stripe Integration documentation.

Symptoms: LemonSqueezy purchases not registering as conversions.

Possible Causes & Solutions:

1. API Connection:
   • Verify your LemonSqueezy API key is correct and active
   • Check that you've enabled the necessary webhook events
2. Webhook URL:
   • Ensure the webhook URL in LemonSqueezy points to the correct Refgrow endpoint
3. Event Filtering:
   • Check that you've selected the correct events to trigger (order_created, etc.)

Symptoms: API requests failing, returning errors, or timing out.

Possible Causes & Solutions:

1. Authentication Issues:
   • Verify your API key is valid and included in the request headers
   • Check for proper formatting of the Authorization header
2. Rate Limiting:
   • Check if you're exceeding the rate limits for your plan
   • Implement retry logic with exponential backoff for 429 responses
3. Invalid Parameters:
   • Review the API documentation to ensure you're sending all required parameters
   • Check parameter formats (dates, IDs, etc.)
4. IP Restrictions:
   • If you've enabled IP restrictions, verify your requests are coming from approved IPs

For more information, see the API Endpoints documentation.

Symptoms: Unable to log in, forgotten password, 2FA issues.

Possible Causes & Solutions:

1. Forgotten Password:
   • Use the "Forgot Password" link on the login page
   • Check your spam folder for reset emails
2. 2FA Problems:
   • Use recovery codes if you've lost access to your authenticator app
   • Ensure your device's time is properly synchronized
3. Account Suspension:
   • Check if your account has been suspended due to billing issues or terms violations
   • Contact support if you believe this is in error

Symptoms: Payment failures, unexpected charges, plan limitations.

Possible Causes & Solutions:

1. Payment Method Issues:
   • Verify your credit card information is current and valid
   • Check if your card has expired or been replaced
2. Subscription Status:
   • Confirm your subscription is active in the billing section
   • Check for any failed payment notices
3. Plan Limitations:
   • Verify you haven't exceeded your plan's limits for affiliates, programs, or API calls
   • Consider upgrading if you're consistently hitting limits

Symptoms: Dashboard takes a long time to load or interact with.

Possible Causes & Solutions:

1. Large Data Volume:
   • If you have thousands of affiliates or transactions, consider narrowing date ranges
   • Use filters to focus on specific segments
2. Script Loading Order:
   • Ensure the Refgrow script is loaded efficiently (consider async or defer attributes)
   • Place the script near the bottom of your page if possible
3. Browser Performance:
   • Clear browser cache and cookies
   • Try a different browser to isolate performance issues

Symptoms: Tracking script slowing down page load or affecting user experience.

Possible Causes & Solutions:

1. Script Loading:
   • Use the async attribute to load the tracking script without blocking page rendering
   • Consider implementing the script with a tag manager for better control
2. Conditional Loading:
   • Only load the full tracking capabilities when a referral parameter is present
   • Use a lightweight script for non-referred visitors
3. Caching:
   • Ensure your CDN or hosting provider properly caches the tracking script

Cause: The API key provided is invalid or expired.

Solution:

1. Generate a new API key in your program settings
2. Ensure you're prefixing the key with "Bearer" in the Authorization header
3. Check for any whitespace or formatting issues in the key

Cause: The program ID provided in the dashboard configuration doesn't exist or is inaccessible.

Solution:

1. Verify the program ID in your dashboard HTML matches what's in your Refgrow account
2. Check that the program is active and not archived
3. Ensure your account has access to this program

Cause: The webhook signature verification failed, often due to mismatched secrets.

Solution:

1. Verify the webhook secret in your integration settings matches what's configured in the service (Stripe, etc.)
2. Check that you haven't regenerated the webhook secret without updating the external service
3. Ensure the webhook payload isn't being modified in transit (by proxies, etc.)