Polar

Connect Polar so orders, refunds, and subscriptions become RefRef facts, and apply discounts and free plan upgrades in Polar.

The Polar integration works in two directions:

  • Facts in. Paid orders, refunds, and subscriptions become purchase Events, purchase adjustments, and Subscription facts in your Project. Your server does not send them to the RefRef API.
  • Rewards out. RefRef applies a Program's discount to the customer's Polar subscription, and delivers its custom Rewards as a free plan upgrade. Polar has no account credit that RefRef can apply, so account credit Rewards go through your product or are recorded by hand.

You connect one Polar organization to each Project. Polar's sandbox (sandbox.polar.sh) and production are separate environments with separate organizations and tokens: a Sandbox Project connects a sandbox token, and a Live Project connects a production token. Start in the Sandbox Project.

Connect Polar

  1. In Polar, open your organization's Settings → Developers and create an organization access token. Give it these scopes: products:read, orders:read, refunds:read, subscriptions:read, subscriptions:write, customers:read, discounts:read, and discounts:write.

  2. In RefRef, open the Project's Settings → Integrations, choose Polar, paste the token, and select Connect. RefRef checks the token with Polar and stores it encrypted.

    Connect Polar in the Integrations settings of a Sandbox Project

  3. The connection shows its webhook URL, which ends in /integrations/v1/polar/webhooks/<connectionId>. Copy it.

  4. In Polar, open Settings → Webhooks, add an endpoint with that URL and the Raw format, and subscribe it to these events:

    Polar eventWhat RefRef records
    order.paidA purchase Event. A subscription order is an invoice; a one-time order is an order.
    refund.created, refund.updatedA refund purchase adjustment, once the refund has succeeded
    subscription.created, subscription.active, subscription.updatedThe start of the Subscription
    subscription.paused, subscription.resumedA pause and a resume
    subscription.canceled, subscription.uncanceled, subscription.revokedThe end of the Subscription, when Polar ends it
  5. Copy the endpoint's secret, paste it into the connection's Signing secret field in RefRef, and select Save. Until you save it, RefRef refuses the endpoint's events.

    The webhook URL and the signing secret of a Polar connection

RefRef checks the signature of each event (Standard Webhooks) and refuses a changed body, a timestamp more than five minutes old, or another secret. A repeated event is stored once.

Name the customer at checkout

RefRef never matches a Polar customer by email. Your server names the participant when it creates the checkout, in the checkout's metadata:

Metadata keyValue
refref_external_idThe participant's externalId in the Project, for example your user ID.
refref_participant_kindindividual (the default) or group, for a team account. Another value names nobody.
refref_handleOptional. The value of the buyer's refref_handle cookie, from the landing script. See Buyers who did not sign up first.

If you already give Polar your user ID as the checkout's external_customer_id, RefRef uses it as the externalId of an individual participant when the metadata has no refref_external_id.

Create a checkout on your server
const checkout = await polar.checkouts.create({
  products: ["<product ID>"],
  externalCustomerId: user.id,
  metadata: {
    refref_external_id: user.id,
    // Optional: the buyer's browser, for a buyer who did not sign up first.
    ...(request.cookies.refref_handle && {
      refref_handle: request.cookies.refref_handle,
    }),
  },
});

Polar copies the checkout's metadata to the order and to the subscription, so renewal orders name the same participant. An order with neither the metadata nor an external customer ID gives no fact.

Buyers who did not sign up first

A buyer who clicked a referral link and then paid, with no earlier signup, has no identified browser yet. Read the buyer's refref_handle cookie and put its value into the same checkout metadata as refref_handle, next to refref_external_id. At the participant's first fact, RefRef identifies that browser to the participant, so the referral click counts.

  • RefRef uses the handle only when the participant has no Event yet, and only when the handle is open and belongs to the Project. A handle that a signup already identified changes nothing.
  • The first fact is the moment of identification: the start of the subscription, or the one-time payment. A click counts when it is at most 90 days before it.
  • A buyer without the cookie, or a checkout without refref_handle, is attributed only through a referral the participant already has.

What RefRef does with the facts

  • First purchase. A billing fact carries no browser data. The start of the subscription uses the referral that the participant already has, for example from a signup that identified the browser. When the participant has no referral yet and purchase is a qualifying event type, the fact can create one from a click in a browser that your backend identified to the participant before, or that the checkout named with refref_handle. Its orders get the referral as their attribution.
  • Renewals. Each later order of the subscription inherits the subscription's referral without a new click, also after the attribution window. A Program rule that pays on each purchase earns a Reward on each paid order.
  • Paid history. Before RefRef evaluates a purchase Reward, it reads the referee's paid orders between the referral and the purchase, so that a "first purchase" rule counts only a first purchase.
  • Refunds. A refund reduces the purchase by its share of the payment, tax excluded. Rewards calculated from that purchase get a matching adjustment. When the purchase is fully refunded, RefRef takes back a Reward that it already delivered: it removes the discount. A partial refund leaves a delivered Reward in place.
  • Missed events. Every five minutes RefRef reads recent Polar orders, refunds, started subscriptions, and ended subscriptions, and records any fact that a webhook did not bring.

Deliver Rewards in Polar

In the Program's settings, open Delivery and choose Give a discount in Polar:

The Delivery settings of a Program connected to Polar

RewardDelivery in Polar
DiscountA percentage discount that RefRef applies to the customer's active subscription from its next billing period, for the rule's duration: the first billing period, the rule's number of months, or every period. A void removes it from the subscription.
Account creditNot available in Polar. Choose Through your product (webhook) or Record by hand.
CustomA free upgrade to a higher plan for a number of billing periods. See Give a free plan upgrade.

Polar cannot limit a discount code to one customer, so RefRef does not issue a code: it applies the discount to the subscription itself. A delivery stops, with a reason in the Console, when the customer has no active subscription or more than one, when the subscription already has another discount (RefRef does not replace it), or when the subscription is set to cancel at the end of its period.

RefRef delivers to the Polar customer of the beneficiary. It learns the customer from the beneficiary's own orders and subscriptions, or finds it by the participant's external ID. A delivery is Polar's success answer.

Not available: account credit, and payouts to referrers through Polar.

Give a free plan upgrade

A custom Reward can move the customer to a higher plan for a number of billing periods. The customer keeps paying the price of the current plan, and then goes back to it automatically.

Set it up

  1. In the Project's Settings → Custom units, add a unit for the upgrade, for example "Pro month".
  2. In the Program's rules, give that unit as a custom Reward with a quantity of 1. A plan upgrade refuses another quantity.
  3. In the Program's Delivery settings, choose Upgrade the plan in Polar for custom Rewards. Under Plan upgrades, enter for the unit the Polar product ID of the higher plan and the number of billing periods, from 1 to 12. A unit without a plan goes through your product (webhook).

The plan upgrade settings of a Program connected to Polar

What the customer gets

Polar changes a plan without a charge only at a renewal, so the upgrade starts at the next renewal (renewal 1). The rest of the current billing period stays on the current plan.

  1. At once, RefRef schedules the higher product and a fixed discount of the price difference for renewal 1.
  2. From renewal 1, for N billing periods, the customer is on the higher plan and pays the higher price less the difference: the customer's current price.
  3. One hour after the renewal that starts the last free period, RefRef schedules the change back to the current product for the next renewal and removes the discount. That renewal bills the current plan, with no charge for the change.

If the customer changed the plan or the subscription ended, RefRef records this at the switch back and changes nothing.

When RefRef does not upgrade

RefRef changes nothing, and the Reward waits for you with the reason, when:

  • The customer has no active or trialing subscription (one set to cancel does not count), or has more than one.
  • The subscription already has a discount.
  • The product that you set is the current product, or its price is not higher.
  • The two products have a different billing interval, or one of them does not have one fixed price in the subscription's currency.

The delivery also fails, for you to resolve, when the subscription already has a scheduled change, when the product is archived, or when the plan has several prices, seats, or metered prices. More than one period is refused for a plan billed by day or week, and for a monthly subscription whose renewal 1 falls on a shortened month end (for example, a subscription that renews on the 31st, with renewal 1 on 28 February): Polar would end the discount before the last free period.

A void before renewal 1 cancels the scheduled change, so the customer never gets the higher plan. A later void schedules the current product for the next renewal; the period that the customer already paid stays on the higher plan.

A connection made before plan upgrades

A Polar connection made before plan upgrades were available does not offer Upgrade the plan in Polar. In Settings → Integrations, select Test connection on the Polar connection. After the test passes, the option is available.

Test the integration

  1. Connect a sandbox token to your Sandbox Project and add the webhook endpoint in the Polar sandbox.
  2. Create a referral link for a participant. Open it in a browser on a page with the landing script, and sign up there, so that your backend identifies the browser with the signup.
  3. Create a checkout with the metadata and pay it with Polar's test card 4242 4242 4242 4242.
  4. In the Sandbox Project, check Referrals and Rewards. A discount that RefRef delivered shows its Polar discount ID, and the subscription in Polar shows the discount.
  5. Refund part of the order in Polar and check the adjustment on the Reward.

The Polar sandbox and production share no data. A sandbox token cannot read a production organization, and a Sandbox Project accepts only a sandbox token.

On this page