Refgrow
Pricing Docs Log in Sign Up

Polar Integration

Automatically track subscriptions and calculate commissions with Polar

Overview

Refgrow integrates with Polar to automatically track subscriptions and calculate commissions for your affiliates.

  • Automatic tracking of subscription creation and renewals
  • Support for product-specific commission rates
  • Support for affiliate-specific commission overrides
  • Secure webhook implementation for real-time tracking
  • Works with Polar's subscription management system

Setting Up Polar Integration

Note: You'll need a Polar account to track subscriptions. If you don't have one, sign up here.

Step 1: Configure Webhook

  1. Go to your project's "Integration" tab
  2. Select "Polar Webhook" as your tracking method
  3. Copy the provided webhook URL
  4. In your Polar dashboard, go to Settings → Webhooks
  5. Create a new webhook with the copied URL
  6. Enable these events: subscription.created, subscription.updated, subscription.canceled, subscription.renewed
  7. Copy the webhook signing secret from Polar
  8. Paste the signing secret in Refgrow and click "Save Secret"

Step 2: Choose Your User Flow

Select the appropriate user conversion flow for your business:

  • Click → Signup → Subscribe: Users create an account before subscribing
  • Click → Subscribe: Users can subscribe directly without signing up first
  • Both: Your platform supports both flows

Passing Referral Codes to Polar

Important: If you have a direct subscription flow (Click → Subscribe), passing the referral code to Polar is essential for correct attribution.

For Polar Subscriptions

When creating a subscription on your server, pass the referral code in the metadata:

// Example (Node.js Server-Side)
const refCode = req.cookies.refgrow_ref_code; // Get code from cookie

const subscription = await polar.subscriptions.create({
  // ... other subscription parameters
  metadata: {
    referral_code: refCode || null // Pass the code here
  }
});

For Polar Checkout

For checkout sessions, include the referral code in the metadata:

// Example (Node.js Server-Side)
const refCode = req.cookies.refgrow_ref_code; // Get code from cookie

const checkout = await polar.checkouts.create({
  // ... other checkout parameters
  metadata: {
    referral_code: refCode || null // Pass the code here
  }
});
Note: Refgrow will automatically process the referral code from the subscription metadata when the webhook is received.

Commission Configuration

Default Commission Settings

Configure your default commission structure in your project settings:

  • Commission Type: Percentage or Fixed Amount
  • Commission Value: The percentage or fixed amount
  • Commission Duration: Lifetime, First Purchase, or Limited Period

Product-Specific Commissions

Override commission rates for specific products:

  1. Go to your project's "Integration" tab
  2. Scroll to "Product-Specific Commissions"
  3. Click "Add Product Commission"
  4. Select a Polar product and set its unique commission rate
Note: Product-specific rates take priority over your default commission settings.

Affiliate-Specific Overrides

Set custom commission rates for individual affiliates:

  1. Go to your "Affiliates" tab
  2. Find the affiliate you want to customize
  3. Click "Manage Override"
  4. Set a custom commission type and value
Priority: Affiliate-specific overrides take highest priority, followed by product-specific commissions, with default settings as the fallback.

How It Works

1. Referral Click

User clicks an affiliate link and the refgrow_ref_code cookie is set.

2. Polar Subscription

The referral code is passed to Polar, and the user completes subscription.

3. Webhook Processing

Refgrow receives the webhook, attributes the subscription, and calculates the commission.

Supported Webhook Events

Refgrow automatically listens for these webhook events:

  • subscription.created - When a new subscription is created
  • subscription.updated - When a subscription is updated
  • subscription.canceled - When a subscription is canceled
  • subscription.renewed - When a subscription is renewed

Troubleshooting

  1. Verify your webhook signing secret is correctly set in your project settings
  2. Check that the webhook endpoint was created with the correct URL: https://refgrow.com/webhook/polar/{your-project-id}
  3. Confirm all required events are enabled for the webhook
  4. Check your Polar dashboard for webhook delivery logs
  5. Ensure the webhook is active and not paused

  1. Ensure the referral code is being passed in the subscription metadata
  2. Check that the affiliate with that referral code exists and is active
  3. Verify the referral code format matches exactly (case-sensitive)
  4. Check that the user hasn't been attributed to another affiliate already
  5. Review the webhook payload to confirm the referral code is present

  1. Check your default commission settings in project configuration
  2. Verify product-specific commission overrides if applicable
  3. Check affiliate-specific commission overrides
  4. Ensure the subscription amount is greater than zero
  5. Review the webhook payload for correct currency and amount values

  1. Check that the same subscription isn't being processed multiple times
  2. Verify webhook retry logic isn't causing duplicates
  3. Review your subscription creation flow to prevent duplicate webhooks
  4. Check the conversion logs for duplicate subscription IDs

API Reference

Webhook Endpoint

POST https://refgrow.com/webhook/polar/{project-id}

Required Headers

Content-Type: application/json
polar-signature: {hmac-sha256-signature}

Webhook Payload Example

{
  "type": "subscription.created",
  "data": {
    "subscription": {
      "id": "sub_123456789",
      "customer": {
        "email": "customer@example.com"
      },
      "price": {
        "amount": 2900,
        "currency": "USD"
      },
      "product": {
        "id": "prod_123456789"
      },
      "metadata": {
        "referral_code": "ABC123"
      }
    }
  }
}

Best Practices

Security
  • Always verify webhook signatures
  • Use HTTPS for all webhook endpoints
  • Keep your webhook secrets secure
  • Monitor webhook delivery logs
Reliability
  • Implement webhook retry logic
  • Handle webhook failures gracefully
  • Monitor webhook delivery status
  • Test webhooks in development first

Need Help?

If you're experiencing issues with your Polar integration:

  • Check the Troubleshooting Guide for common solutions
  • Review your webhook delivery logs in your Polar dashboard
  • Contact our support team with your project ID and specific error details
  • Join our Discord community for help from other users