Polar

This guide is the canonical reference for the Polar sale path. Polar is a merchant of record, so there is no Stripe account to connect — instead, your app hosts a small webhook route that reports every paid order to Affitor.

PrerequisitesCopy Anchor Link

• Your program ID and a program API key (run npx affitor init, or dashboard → program settings)
• A Polar organization with checkout working in your app
• Access to your Polar organization's webhook settings. Sandbox is a separate environment with its own tokens and its own webhook endpoints (sandbox-api.polar.sh).

What you will set upCopy Anchor Link

In your Polar organization, add a webhook endpoint delivering order.paid, refund.created and refund.updated to a route in your own app — https://<your domain>/api/polar/webhook in the examples below — and store the signing secret Polar gives you as POLAR_WEBHOOK_SECRET. The rest of this page is the route that receives those deliveries, plus the click and signup steps that come before it.

1. Capture clicks and track signupsCopy Anchor Link

Identical to the framework integration — follow Step 1 and Step 2 in the Next.js guide, or your framework's equivalent.

Keep the userId you send at signup (signup(userId) / trackLead({ customerExternalId: userId })) — you will plant it on every Polar checkout as user_id.

2. Carry attribution into the checkoutCopy Anchor Link

Polar copies checkout metadata onto the resulting Order and Subscription, so the webhook can resolve the partner days later. Two carriers work; use whichever fits your checkout:

Server-created Checkout SessionsCopy Anchor Link

// When creating the Polar checkout server-side, attach metadata:
metadata: {
  affitor_click_id: affitorClickId,   // from the `affitor_click_id` cookie
  user_id: user.id,                   // SAME stable id you used at signup
}

Checkout Links (zero server code)Copy Anchor Link

Append the click id to the link — Polar automatically copies a ?reference_id= query param into the checkout's metadata, and it propagates to every resulting order, renewals included:

https://buy.polar.sh/polar_cl_xxx?reference_id=<affitor_click_id>

If you use the @polar-sh/nextjs Checkout route handler instead, pass customerExternalId (your user id) and a URL-encoded metadata JSON query param — the adapter forwards both.

3. The webhook glue routeCopy Anchor Link

Create app/api/polar/webhook/route.ts (Next.js App Router). The Webhooks() helper validates the Standard-Webhooks signature with POLAR_WEBHOOK_SECRET before any callback runs:

import { Webhooks } from '@polar-sh/nextjs';
import { Affitor } from '@affitor/sdk/server';

const affitor = new Affitor({ apiKey: process.env.AFFITOR_API_KEY ?? '' });

export const POST = Webhooks({
  webhookSecret: process.env.POLAR_WEBHOOK_SECRET!,
  onOrderPaid: async (payload) => {
    const order = payload.data;
    // Skip $0 orders (free tiers, 100%-off) — no revenue to attribute.
    if (!order.totalAmount || order.totalAmount <= 0) return;
    const res = await affitor.trackSale({
      customerExternalId: (order.metadata?.user_id as string | undefined)
        ?? order.customer?.externalId ?? order.customerId,
      clickId: (order.metadata?.affitor_click_id ?? order.metadata?.reference_id) as string | undefined,
      amount: order.totalAmount,         // integer cents
      currency: order.currency,
      invoiceId: order.id,               // idempotency key — 409 = already recorded
      saleType: order.subscriptionId ? 'subscription' : 'payment',
      isRecurring: order.billingReason === 'subscription_cycle',
      subscriptionId: order.subscriptionId ?? undefined,
    });
    if (!res.ok && res.status !== 409) {
      console.error('[affitor] trackSale failed', res.status, res.error);
    }
  },
  // One call per refund, with that refund's own amount. Polar sends refund.created
  // "regardless of status", so report only once the refund has succeeded; a repeat
  // with the same amount (created + updated both succeeded) is ignored by Affitor.
  onRefundCreated: async (payload) => reportRefund(payload.data),
  onRefundUpdated: async (payload) => reportRefund(payload.data),
});

async function reportRefund(refund: { status: string; orderId: string; amount: number; taxAmount?: number }) {
  if (refund.status !== 'succeeded') return;
  const res = await affitor.trackRefund({
    invoiceId: refund.orderId,                             // the ORDER id you sent as the sale's invoiceId
    refundAmountCents: refund.amount + (refund.taxAmount ?? 0), // same basis as the sale (order.totalAmount includes tax)
  });
  if (!res.ok) {
    console.error('[affitor] trackRefund failed', res.status, res.error);
  }
}

Attribution resolution. Affitor resolves the partner from, in order: clickId (the planted affitor_click_id, or the checkout link's reference_id), then customerExternalId matched against the lead you tracked at signup. Supplying both is the recommended default.

Subscription renewalsCopy Anchor Link

Nothing extra to wire: Polar fires order.paid on every billing cycle, and the metadata planted at checkout (or carried by reference_id) propagates to renewal orders. The handler above marks renewals precisely via billingReason === 'subscription_cycle' (first subscription payments arrive as subscription_create).

RefundsCopy Anchor Link

Report each refund once, with that refund's own amount, after it has succeeded (the handler above does this from refund.created / refund.updated). Use the same tax basis as the sale amount you sent; amounts add up on the sale, and the commission is reversed once they reach the sale amount. Omit refundAmountCents to refund everything not yet refunded. Do not pass order.refundedAmount from order.refunded: it is a running total, and each call is counted as a new refund. A retry with the same amount is ignored; to report two separate refunds of the same amount, call the HTTP endpoint with a distinct refund_id for each.

VerifyCopy Anchor Link

Common mistakesCopy Anchor Link