Polar Integration

Overview

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

• Automatic tracking of one-time purchases, first subscription payments, 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

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: order.paid, order.refunded, and subscription.canceled. Paid orders cover one-time purchases, the first payment for a subscription, and recurring payments.
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

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
  }
});

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

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

How It Works

Supported Webhook Events

Refgrow automatically listens for these webhook events:

• order.paid - A paid one-time purchase, first subscription payment, or renewal
• order.refunded - A full or partial refund for a paid order
• subscription.canceled - A subscription cancellation status update

Subscription cancellation does not reverse commissions that were already recorded for paid orders. Refunds are handled through theorder.refunded event.

Commission Amount

Refgrow uses Polar's net_amount from the paid order. It is the amount in cents after discounts and before tax, so tax is excluded from the commission base.

Troubleshooting

Webhooks Not Working

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 order.paid, order.refunded, and subscription.canceled are enabled for the webhook
4. Check your Polar dashboard for webhook delivery logs
5. Ensure the webhook is active and not paused

Referral Codes Not Being Tracked

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 has not been attributed to another affiliate already
5. Review the webhook payload to confirm the referral code is present

Commissions Not Calculating Correctly

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 paid order's net_amount is greater than zero
5. Review the webhook payload for the correct currency and net_amount

Duplicate Conversions

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

API Reference

Webhook Endpoint

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

Required Headers

Content-Type: application/json
webhook-id: {unique-event-id}
webhook-timestamp: {unix-timestamp}
webhook-signature: {standard-webhooks-signature}

Webhook Payload Example

{
  "type": "order.paid",
  "timestamp": "2026-01-01T12:00:00Z",
  "data": {
    "id": "order_123456789",
    "paid": true,
    "status": "paid",
    "billing_reason": "subscription_cycle",
    "net_amount": 2900,
    "tax_amount": 580,
    "total_amount": 3480,
    "currency": "usd",
    "customer": { "email": "customer@example.com" },
    "product_id": "prod_123456789",
    "subscription_id": "sub_123456789",
    "metadata": { "referral_code": "ABC123" }
  }
}

Polar signs raw webhook payloads using the Standard Webhooks headers shown above. Keep the raw request body available for signature verification and store the webhook secret securely.

Best Practices

Need Help?

If you are 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