Troubleshooting

Overview

This guide addresses common issues you might encounter when using Refgrow and provides step-by-step solutions. If you don't find an answer to your specific problem, please contact our support team.

Dashboard Issues

Dashboard Not Loading

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 the following domains to your script-src directive:
     • https://scripts.refgrowcdn.com - Required for the tracking script (latest.js)
     • https://*.refgrow.com or https://refgrow.com - Required for the affiliate dashboard widget (embed.js)
   • Also add https://*.refgrow.com or https://refgrow.com to your connect-src directive for API calls
   • Example CSP header:
     HTTPCopy

     Content-Security-Policy: script-src 'self' 'unsafe-eval' 'unsafe-inline' https://scripts.refgrowcdn.com https://*.refgrow.com https://refgrow.com; connect-src 'self' https://*.refgrow.com https://refgrow.com;

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

Dashboard Styling Issues

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

Authentication Problems

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

Tracking Issues

Referrals Not Being Tracked

1. Verify the tracking script is on all pages with links
2. Check your browser console for any error messages
3. Ensure third-party cookies are not blocked
4. Test with a known referral link format (e.g., yoursite.com?ref=CODE)
5. Verify the referral parameter name matches your project settings

Conversions Not Attributing to Affiliates

For Stripe/LemonSqueezy:

• Ensure webhooks are properly configured
• Verify you're passing the referral code to the checkout metadata
• Check webhook logs in your payment provider dashboard

For Manual Tracking:

• Ensure you're providing a valid email address in the tracking call
• Verify the cookie exists when making the conversion call
• Check your browser console for any API errors

Affiliate Dashboard Issues

• Verify the embed script is correctly installed
• Check if there are any JavaScript errors in the browser console
• Ensure your container element has sufficient width and height
• Verify your project's customization settings

Inaccurate Reporting

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

Integration Issues

Stripe Integration Failures

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.

LemonSqueezy Integration Issues

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.)

API Integration Problems

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.

Account & Billing Issues

Account Access Problems

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

Billing and Subscription Issues

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

Performance Optimization

Slow Dashboard Loading

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

Optimizing Tracking Script Performance

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

Common Error Messages

API Error: "Invalid Authentication"

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

Dashboard Error: "Program ID Not Found"

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

Webhook Error: "Invalid Signature"

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.)

Getting Help

If you've tried the troubleshooting steps above and still can't resolve your issue, there are several ways to get additional help:

For urgent issues affecting your production environment, Pro and Business customers can access priority support with faster response times.

Next Steps

• Review your tracking implementation
• Check the integration guides for platform-specific issues (Stripe, LemonSqueezy, Paddle)
• Learn about security best practices to avoid common problems