Install on Polar

Polar is a Merchant of Record: your customer pays Polar and Polar remits to you, so there is no merchant Stripe account to connect. Rekomi supports it natively with a one-paste setup: you paste a single Organization Access Token into Rekomi, and Rekomi does the rest. It validates the token, resolves your organization, and creates the webhook endpoint in your Polar organization itself; there is no manual webhook configuration and nothing to paste on Polar's side. From that point on, orders, subscription renewals, and refunds flow into Rekomi with no relay code to write or maintain. Still evaluating? See Why Rekomi for Polar →.

What you need

One Organization Access Token. In Polar, open your Organization Settings, find the Developers section, and create a token with these scopes:

• organizations:read
• webhooks:read
• webhooks:write

Set the expiration to "No expiration" so the connection never lapses on a timer. The token starts with polar_oat_. Rekomi uses it to create and health-check the webhook endpoint; commissions and money flow are never touched through it.

Connect in Rekomi

Step 1. Go to /dashboard/setup/polar and paste the token. Rekomi validates it live, resolves your Polar organization, and creates the webhook endpoint automatically, subscribed to exactly the events Rekomi needs:

• order.paid
• subscription.created
• subscription.canceled
• subscription.revoked
• subscription.uncanceled
• refund.created
• refund.updated

Polar generates the webhook signing secret when the endpoint is created; Rekomi stores it encrypted and verifies the signature on every delivery. The setup page shows the endpoint's URL and event list for reference only.

Step 2. That's it for the connection. The remaining work is attribution: carrying the affiliate referral into checkout, below.

Attribution: carry rekomi_ref into checkout (required)

Polar hosts the checkout on its own domain, so the affiliate referral has to travel from the visitor's browser into the order. This step is required: without it, orders arrive with no referral and Rekomi falls back to the customer's earlier conversion history (which cannot credit a first purchase).

First, make sure the Rekomi head script is installed on your marketing site so the affiliate click is captured when a visitor lands on an affiliate link:

<script>
  (function(){
    var s=document.createElement('script');
    s.src='https://js.rekomi.com/v1/rekomi.js';
    s.async=true;
    s.dataset.programId='YOUR_PROGRAM_ID';
    document.head.appendChild(s);
  })();
</script>

The program ID is in Settings > Tracking in the Rekomi dashboard.

Then pick the recipe that matches how you sell:

Creating checkouts via Polar's API. Stamp metadata.rekomi_ref (the canonical key) when you create the checkout. Read the referral on your frontend with window.Rekomi.getReferral() and send it to your backend with the checkout request:

const ref = window.Rekomi && window.Rekomi.getReferral();
await polar.checkouts.create({
  products: ["your-product-id"],
  metadata: ref ? { rekomi_ref: ref } : {},
});

Using Polar checkout links. Append reference_id to the link; Polar copies it into the order's metadata (metadata.reference_id, the secondary key Rekomi also reads):

<script>
  document.addEventListener('DOMContentLoaded', function () {
    var ref = window.Rekomi && window.Rekomi.getReferral();
    if (!ref) return;
    document
      .querySelectorAll('a[href*="buy.polar.sh"], a[href*="polar.sh/checkout"]')
      .forEach(function (a) {
        var url = new URL(a.href);
        url.searchParams.set('reference_id', ref);
        a.href = url.toString();
      });
  });
</script>

Rekomi reads metadata.rekomi_ref first, then metadata.reference_id. If you already use reference_id for your own bookkeeping, keep using it; a value that matches no affiliate is simply ignored, and the rekomi_ref key stays free for attribution.

What gets recorded

• Orders are recorded when order.paid fires: a first purchase is a one-time conversion, and subscription renewals are recurring conversions, so recurring revenue-share commissions keep accruing automatically. The referral stamped at checkout stays on the subscription, so renewals credit the same affiliate; Rekomi also falls back to the customer's conversion history.
• Commission basis is the net order amount: after discounts and excluding tax (Polar, as Merchant of Record, collects the tax; it is never commissioned), and net of any customer-balance credit Polar applied. Trials produce a $0 order at trial start; Rekomi skips it and records the real first charge when it arrives.
• Subscription lifecycle events (created, canceled, revoked, uncanceled) are recorded so churn-aware commissions reverse on cancellation and resume on reactivation.
• Refunds, full or partial, claw back the commission automatically and proportionally, in the same audit trail as the original conversion. The refunded amount is pre-tax, symmetric with the commission basis.

Refunds and chargebacks

Refunds you issue in Polar arrive as refund events and reverse commission proportionally: a 40% refund claws back 40% of the commission. Because Polar is the Merchant of Record, disputes and chargebacks are handled by Polar and reach Rekomi through the same refund pipe when they result in a refund, so clawbacks stay automatic. Pending refunds are not clawed back until they succeed.

Security

• Every webhook delivery is verified against the Polar-generated signing secret (standard-webhooks HMAC signatures with a 5-minute replay window) before anything is processed; deliveries that fail verification are rejected.
• Your Organization Access Token and the webhook signing secret are stored encrypted at rest and never returned by the API. Disconnecting wipes both, deletes the webhook endpoint Rekomi created in your Polar organization, and retires the per-workspace URL.
• The token's three scopes are read/webhook-only; Rekomi never modifies products, prices, or payouts in your Polar account.

Quirks worth knowing

• One conversion source per workspace. Polar Connect is mutually exclusive with Stripe Connect, Paddle, Braintree, Shopify, Lemon Squeezy, Chargebee, Recurly, Gumroad, Creem, Dodo Payments, and the S2S API, so the same sale is never counted twice. Disconnect one before connecting another.
• Tokens need not expire. Pick "No expiration" when creating the token. If the token is ever revoked, the health check flags the connection as broken, shows a reconnect banner, and emails you; pasting a fresh token restores the connection with history intact.
• Polar auto-disables failing endpoints. After repeated failed deliveries Polar disables a webhook endpoint. Rekomi's health check detects this state specifically: re-enable the endpoint in Polar's webhook settings, or simply reconnect in Rekomi (which recreates the endpoint fresh).
• Reconnecting rotates the secret. A reconnect deletes the old endpoint and creates a new one, which mints a fresh Polar-generated signing secret; nothing to copy manually.
• Sandbox is a separate universe. Polar's sandbox (sandbox.polar.sh) has its own accounts and tokens. Production Rekomi accepts production tokens; a sandbox token pasted in production is rejected with a clear error.

Troubleshooting

"Connection needs attention" banner or reconnect email. Either the stored token stopped validating (revoked or expired in Polar) or the webhook endpoint was deleted or disabled. Reconnect on /dashboard/setup/polar with a fresh Organization Access Token; your tracking history is preserved.

Polar disabled the webhook endpoint. Polar switches an endpoint off after repeated delivery failures. Re-enable it in Polar's Organization Settings > Webhooks, or reconnect in Rekomi to recreate it. The connection check on the setup page tells you when this is the reason.

Orders arrive but no affiliate is credited. The order reached Rekomi without a referral in its metadata. Verify the stamping snippet runs on every page that links to checkout, that the head script ran before the buyer clicked through (so window.Rekomi.getReferral() has a value), that API-created checkouts set metadata.rekomi_ref, and that checkout links carry reference_id.

Token rejected at connect. Check the token was copied in full (it starts with polar_oat_), has the organizations:read, webhooks:read, and webhooks:write scopes, and has not expired or been revoked.

Related

• S2S tracking API reference
• JavaScript pixel reference
• Refund handling